# Crear scripts

## Crear scripts al &kile;

La característica de crear scripts del &kile; permet l'execució de codi ECMAScript, també conegut com a &javascript;. Trobareu una gran quantitat de guies d'aprenentatge que proporcionen informació sobre els objectes (variables), funcions i propietats suportades per &javascript;.

El suport per a crear scripts es pot activar al diàleg de configuració del &kile;: Arranjament Configura el &kile;... Kile Crea scripts. Activant o desactivant la compatibilitat amb crear scripts Activant o desactivant la compatibilitat amb crear scripts

Si la creació de scripts està activada, serà visible un grup addicional de crear scripts a la barra lateral, des d'on es podran gestionar: El plafó Crear scripts a la barra lateral El plafó Crear scripts a la barra lateral

Aquest estri conté sis icones, les quals ofereixen tasques diferents:

- Executa l'script seleccionat.

- Crea un script nou.

- Obre l'script seleccionat a l'editor.

- Configura una seqüència de tecles per a l'script seleccionat.

- Elimina una seqüència de tecles assignada.

- Actualitza la llista de scripts disponibles, els quals es troben a `$`KDEDIR`/share/apps/kile/scripts/`.

## Executar un script

Podeu executar un script de tres maneres diferents:

1. Seleccioneu l'script desitjat i feu clic sobre el botó Executa a la part esquerra de l'estri per a la gestió de scripts.

   Crear scripts: el botó Executa
   Crear scripts: el botó Executa

2. Utilitzeu una drecera de teclat.

   Crear scripts: drecera de teclat
   Crear scripts: drecera de teclat

   Podeu assignar una drecera de teclat a un script utilitzant el botó Configura a l'estri per a la gestió de scripts.

   Crear scripts: el diàleg configura seqüència
   Crear scripts: el diàleg configura seqüència

3. Utilitzeu un editor per a seqüència de tecles. L'script serà executat, si escriviu a l'editor la seqüència de tecles assignada.

   Crear scripts: editor de seqüència de tecles
   Crear scripts: editor de seqüència de tecles

   Aquest mètode es pot estendre a un tipus força sofisticat de compleció de codi. Suposem que heu escrit un script, el qual simplement insereix l'ordre `\textbf{}` de &latex; en el document actual.

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

   Si ara escriviu la seqüència de tecles assignada `bfx` en el vostre document de text, aquesta seqüència de tecles serà eliminada i s'executarà l'script. S'inserirà `\textbf{}` i el cursor se situarà entre les claus.

   Crear scripts: escriure una seqüència de tecles a l'editor
   Crear scripts: escriure una seqüència de tecles a l'editor

   Realment és un mètode còmode i potent per a la finalització de codi.

## Referència de l'API

La API per a la creació de scripts que es presenta aquí està disponible en tots els scripts. Abans que es carregui el contingut d'un script, el &kile; primer afegeix diversos prototips i funcions al context de la creació de scripts. Aquesta utilitat de l'API conté prototips com cursors de text i intervals de text, i està localitzada a la carpeta `KILE_APP_DIR/script-plugins/`.

Els scripts del &kile; difereixen lleugerament dels scripts del &kate;, els quals utilitzen un altre disseny, ja que també es poden iniciar des de la línia d'ordres. Però totes les funcions de l'API per a crear scripts del &kate; també estan disponibles a l'API per a crear scripts del &kile;, portar el codi &javascript; del &kate; al &kile; hauria de ser molt fàcil. Però com el &kile; és un editor de &latex; molt ric en característiques, la seva pròpia API per a crear scripts ofereix moltes més possibilitats que la del &kate;.

Observació: La descripció de les crides a l'API, que també estan disponibles a la creació de scripts del &kate;, han estat agafades de la documentació del &kate;.

### Funcions globals

Aquesta secció llista les funcions globals.

    void debug(String text);

  Imprimeix el `text` a `stdout` a la consola. El text imprès restarà en color per a distingir-lo d'una altra sortida de depuració.

### El prototip «Cursor»

Com el &kile; és un editor de text, tota l'API per a la creació de scripts es basa en cursors i intervals sempre que és possible. Un cursor és una simple tupla `(línia, columna)` que representa una posició del text en el document.

    Cursor();

  Constructor. Retorna un cursor a la posició `(0,0)`.

  Exemple: `var cursor = new Cursor();`

    Cursor(int línia, int columna);

  Constructor. Retorna un cursor a la posició (línia,columna).

  Exemple: `var cursor = new Cursor(3,42);`

    Cursor(Cursor altra);

  Constructor de còpia: Retorna una còpia del cursor `altra`.

  Exemple: `var copy = new Cursor(altra);`

    Cursor Cursor.clone();

  Retorna una còpia del cursor.

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

    bool Cursor.isValid();

  Comprova si el cursor és vàlid. El cursor no és vàlid, si la línia i/o la columna s'estableix a `-1`.

  Exemple: `var valid = cursor.isValid();`

    Cursor Cursor.invalid();

  Retorna un nou cursor no vàlid situat a `(-1,-1)`.

  Exemple: `var invalidCursor = cursor.invalid();`

    int Cursor.compareTo(Cursor altra);

  Compara aquest cursor al cursor `altra`. Retorna

  - `-1`, si el cursor està situat abans del cursor `altra`,

  - `0`, si tots dos cursors són iguals i

  - `+1`, si el cursor està situat després del cursor `altra`.

    bool Cursor.equals(Cursor altra);

  Retorna `true` (vertader), si aquest cursor i el cursor `altra` són iguals, en cas contrari retornarà `false` (fals).

    String Cursor.toString();

  Retorna el cursor com una cadena de la forma `Cursor(línia, columna)`.

### El prototip «Range»

Com el &kile; és un editor de text, tota l'API per a la creació de scripts es basarà en cursors i rangs sempre que és possible. Un cursor és una simple tupla `(línia, columna)` que representa una posició del text en el document, abasta un rang de text des d'una posició de començament del cursor fins a una posició de finalització del cursor.

    Range();

  El constructor. Crida `new Range()` retornant un interval `(0,0) - (0,0)`.

    Range(Cursor inici, Cursor final);

  Constructor: Crida `new Range(inici, final)` retorna l'interval des del cursor `inici` fins al cursor `final`.

    Range(int iniciLínia, int iniciColumna, int finalLínia, int finalColumna);

  El constructor: Crida `new Range(iniciLínia, iniciColumna, finalLínia, finalColumna)` retorna l'interval des de (`iniciLínia`, `iniciColumna`) a (`finalLínia`, `finalColumna`).

    Range(Range altra);

  Constructor de còpia: Retorna una còpia de l'interval `altra`.

    Range Range.clone();

  Retorna una còpia de l'interval.

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

    bool Range.isValid();

  Retorna `true` (vertader), si inici i final del cursor són vàlids, en cas contrari retornarà `false` (fals).

  Exemple: `var valid = range.isValid();`

    bool Range.invalid();

  Retorna l'interval de (-1,-1) a (-1,-1).

    bool Range.contains(Cursor cursor);

  Retorna `true` (vertader) si aquest interval conté la posició de cursor, en cas contrari retornarà `false` (fals).

    bool Range.contains(Range altra);

  Retorna `true` (vertader), si aquest interval conté l'interval `altra`, en cas contrari retornarà `false` (fals).

    bool Range.containsColumn(int columna);

  Retorna `true` (vertader), si `columna` està en l'interval obert mig `[start.column, end.column]`, en cas contrari retornarà `false` (fals).

    bool Range.containsLine(int línia);

  Retorna `true` (vertader), si `línia` està en l'interval obert mig `[start.line, end.line]`, en cas contrari retornarà `false` (fals).

    bool Range.overlaps(Range altra);

  Retorna `true` (vertader), si aquest interval i l'interval `altra` comparteixen una regió comuna, en cas contrari retornarà `false` (fals).

    bool Range.overlapsLine(int línia);

  Retorna `true` (vertader), si `línia` està en l'interval `[start.line, end.line]`, en cas contrari retornarà `false` (fals).

    bool Range.overlapsColumn(int columna);

  Retorna `true` (vertader), si `columna` està en l'interval `[start.column, end.column]`, en cas contrari retornarà `false` (fals).

    bool Range.equals(Range altra);

  Retorna `true` (vertader), si aquest interval i l'interval de `altra` són iguals, en cas contrari retornarà `false` (fals).

    String Range.toString();

  Retorna l'interval com una cadena de la forma `Range(Cursor(línia,columna) - Cursor(línia,columna))`.

### La API «View»

Sempre que s'està executant un script, hi haurà un objecte global (variable) «`view`» que representa la vista actual de l'editor actiu. Totes les funcions de «`view`» treballen amb les posicions del cursor o el text seleccionat. La següent és una llista de totes les funcions disponibles per a «`view`».

    void view.backspace();

  Realitza la programació equivalent a prémer la tecla de retrocés.

    Cursor view.cursorPosition();

  Retorna la posició actual del cursor en la vista.

    void view.setCursorPosition(int línia, int columna);
    void view.setCursorPosition(Cursor cursor);

  Estableix la posició actual del cursor a `línia`, `columna` o el `cursor` indicat.

    void view.cursorLeft();

  Mou el cursor una posició cap enrere en el text.

    void view.cursorRight();

  Mou el cursor una posició cap endavant en el text.

    void view.cursorUp();

  Mou el cursor una línia cap amunt en el document.

    void view.cursorDown();

  Mou el cursor una línia cap avall en el document.

    int view.cursorLine();

  Retorna a la línia en la que està situat el cursor.

    int view.cursorColumn();

  Retorna a la columna en la que està el cursor.

    void view.setCursorLine(int línia);

  Estableix la línia del cursor a la `línia` donada.

    void view.setCursorColumn(int columna);

  Estableix la columna del cursor a la `columna` donada.

    Cursor view.virtualCursorPosition();

  Obté la posició actual del cursor virtual. Virtual vol dir que el caràcter tabulador (TAB) compta amb múltiples caràcters, tal com l'ha configurat l'usuari (&pex;, un TAB són 8 espais). La posició del cursor virtual proporciona accés als valors d'usuari visibles de la posició actual del cursor.

    bool view.hasSelection();

  Retorna `true` (vertader), si la vista conté el text seleccionat, en cas contrari retornarà `false` (fals).

    String view.selectedText();

  Retorna el text seleccionat. Si no hi ha text seleccionat, la cadena retornada estarà buida.

    Range view.selectionRange();

  Retorna l'interval de text seleccionat. L'interval retornat no serà vàlid si no hi ha text seleccionat.

    void view.setSelection(Range rang);

  Estableix el text seleccionat al `rang` indicat.

    void view.selectAll();

  Selecciona tot el text en el document.

    void view.clearSelection();

  Neteja la selecció de text sense eliminar-lo.

    void view.removeSelectedText();

  Elimina el text seleccionat. Si la vista no té cap text seleccionat, no fa res.

    void view.selectLine();

  Selecciona el text a la línia actual.

    void view.selectLine(int línia);

  Selecciona el text a la `línia` indicada.

    void view.selectLines(int des_de, int fins_a);

  Selecciona tot el text des de la línia `des_de` fins a la línia `fins_a`.

    void view.selectWord();

  Selecciona la paraula actual. Si no es troba cap paraula a la posició actual del cursor, no es farà res.

    void view.selectLatexCommand();

  Selecciona l'ordre de &latex; actual. Si no es troba cap ordre a la posició actual del cursor, no es farà res.

    void view.selectEnvironment(bool inside = false);

  Selecciona tot el text d'entorn de &latex; actual. Si el paràmetre `inside` és `false` (fals), es podrà seleccionar tot el text d'entorn, incloses les etiquetes de &latex; circumdants `\begin{...}...\end{...}`, en cas contrari aquestes etiquetes seran excloses. Si no s'especifica cap paràmetre, `inside` restarà establert a `false`.

    void view.selectTexgroup(bool inside = true);

  Selecciona el text del grup de &latex; actual. Si el paràmetre `inside` és `true` (vertader), només se seleccionarà el grup de TeX sense les claus circumdants. Si no s'especifica cap paràmetre, `inside` restarà establert a `true`.

    void view.selectMathgroup();

  Selecciona el text del grup matemàtic actual.

    void view.selectParagraph(bool wholeLines = true);

  Selecciona el text sencer del paràgraf de &latex; actual. Si el paràmetre `wholeLines` és `true` (vertader), la primera i última línies del paràgraf seran incloses en la selecció (incloent-hi el caràcter de final de línia), en cas contrari, la selecció només contindrà caràcters sense espais en blanc.

### La API «Document»

Sempre que s'està executant un script, hi haurà un objecte global (variable) «`document`» que representa la vista actual del document actiu. La següent és una llista de totes les funcions disponibles per a «`document`».

    void document.insertText(String text);

  Insereix el `text` a la posició actual del cursor.

    void document.insertText(int línia, int columna, String text);
    void document.insertText(Cursor cursor, String text);

  Insereix el `text` a la posició donada del cursor.

    bool document.removeText(int des_deLínia, int des_deColumna, int fins_aLínia, int fins_aColumna);
    bool document.removeText(Cursor des_de, Cursor fins_a);
    bool document.removeText(Range rang);

  Elimina el text dins de l'interval donat. Retorna `true` (vertader) en cas d'èxit, o `false` (fals), si el document està en mode de només lectura.

    bool document.replaceText(Range rang, String text);

  Substitueix el text de l'interval donat amb el text especificat.

    int document.lines();

  Retorna el nombre de línies en el document.

    int document.length();

  Retorna el nombre de caràcters en el document.

    Range document.documentRange();

  Retorna un rang que abasta tot el document.

    Cursor document.documentEnd();

  Retorna la posició actual del cursor del final del document.

    String document.text();

  Retorna el contingut complet del document en una cadena de text única. Els salts de línia estan marcats amb el caràcter de nova línia `\n`.

    String document.text(int des_deLínia, int des_deColumna, int fins_aLínia, int fins_aColumna);
    String document.text(Cursor des_de, Cursor fins_a);
    String document.text(Range rang);

  Retorna el text en l'interval donat. Es recomana utilitzar el cursor i la versió basada en l'interval per a una millor lectura del codi font.

    bool document.setText(String text);

  Estableix el text a tot el document.

    bool document.clear();

  Elimina tot el text en el document.

    String document.line();

  Retorna la línia de text actual com a cadena.

    String document.line(int línia);

  Retorna la línia de text donada com a cadena. La cadena estarà buida si la línia demanada està fora de l'interval.

    int document.lineLength();

  Retorna la longitud de la línia actual.

    int document.lineLength(int línia);

  Retorna la longitud de la `línia`.

    bool document.insertLine(String s);

  Insereix text en la línia actual. Retorna `true` (vertader) en cas d'èxit, o `false` (fals), si el document està en mode de només lectura o la línia no està en l'interval document.

    bool document.insertLine(int línia, String s);

  Insereix text en la línia donada. Retorna `true` (vertader) en cas d'èxit, o `false` (fals), si el document està en mode de només lectura o la línia no està en l'interval document.

    bool document.removeLine();

  Elimina la línia de text actual. Retorna `true` (vertader) en cas d'èxit, o `false` (fals), si el document està en mode de només lectura.

    bool document.removeLine(int línia);

  Elimina la línia de text donada. Retorna `true` (vertader) en cas d'èxit, o `false` (fals), si el document està en mode de només lectura o la línia no està en l'interval document.

    bool document.replaceLine(String text);

  Substitueix el text de la línia actual amb el text especificat.

    bool document.replaceLine(int línia, String text);

  Substitueix el text de la línia donada amb el text especificat.

    bool document.truncateLine();

  Trunca la línia actual a la columna o la posició donada del cursor. Retorna `true` (vertader) en cas d'èxit, o `false` (fals) si la línia donada no forma part de l'interval del document.

    bool document.truncate(int línia, int columna);
    bool document.truncate(Cursor cursor);

  Trunca la línia donada a la columna o la posició donada del cursor. Retorna `true` (vertader) en cas d'èxit, o `false` (fals) si la línia donada no forma part de l'interval del document.

    String document.word();

  Retorna la paraula a la posició actual del cursor. Si no es troba cap paraula en aquesta posició del cursor, la cadena retornada estarà buida.

    String document.wordAt(int línia, int columna);
    String document.wordAt(Cursor cursor);

  Retorna la paraula a la posició donada del cursor. Si no es troba cap paraula en aquesta posició del cursor, la cadena retornada estarà buida.

    Range document.wordRange();

  Retorna l'interval de la paraula a la posició donada del cursor. Si no es troba cap paraula, es retornarà `Range.invalid()`, el qual es pot provar amb `Range.isValid()`.

    String document.latexCommand();

  Retorna l'ordre de &latex; a la posició actual del cursor. Si no es troba cap ordre en aquesta posició del cursor, la cadena retornada estarà buida.

    String document.latexCommandAt(int línia, int columna);
    String document.latexCommandAt(Cursor cursor);

  Retorna l'ordre de &latex; a la posició donada del cursor. Si no es troba cap ordre en aquesta posició del cursor, la cadena retornada estarà buida.

    Range document.latexCommandRange();

  Retorna l'interval de l'ordre de &latex; a la posició donada del cursor. Si no es troba l'ordre de &latex;, es retornarà `Range.invalid()`, el qual es pot provar amb `Range.isValid()`.

    String document.charAt(int línia, int columna);
    String document.charAt(Cursor cursor);

  Retorna el caràcter a la posició donada del cursor.

    String document.firstChar(int línia);

  Retorna el primer caràcter en la `línia` donada que no és un espai en blanc. El primer caràcter és a la columna 0. Si la línia està buida o només conté espais en blanc, la cadena retornada estarà buida.

    String document.lastChar(int línia);

  Retorna l'últim caràcter de la `línia` donada que no és un espai en blanc. Si la línia està buida o només conté espais en blanc, la cadena retornada estarà buida.

    bool document.isSpace(int línia, int columna);
    bool document.isSpace(Cursor cursor);

  Retorna `true` (vertader), si el caràcter a la posició donada del cursor és un espai en blanc, en cas contrari retornarà `false` (fals).

    void document.insertBullet();

  Insereix un pic del &kile;. Recordeu que podeu saltar amb facilitat al pic següent o anterior. Això també ressaltarà aquest pic, eliminant-lo de forma automàtica en introduir la primera lletra.

    void document.nextBullet();

  Salta al següent pic al text si és que existeix.

    void document.previousBullet();

  Salta al pic anterior al text si és que existeix.

    bool document.hasEnvironment();

  Retorna `true` (vertader) si es troba un entorn de &latex; circumdant, d'altra manera `false` (fals).

    String document.environment(bool inside = false);

  Retorna tot el text d'entorn de &latex; circumdant. Si el paràmetre `inside` és `false` (fals), es podrà seleccionar tot el text d'entorn, incloses les etiquetes de &latex; circumdants `\begin{...}...\end{...}`, en cas contrari aquestes etiquetes seran excloses. Si no s'especifica cap paràmetre, `inside` restarà establert a `false`.

    Range document.environmentRange(bool inside = false);

  Retorna l'interval de l'entorn de &latex; circumdant. Si el paràmetre `inside` és `false` (fals), es podrà seleccionar tot l'interval de l'entorn, incloses les etiquetes de &latex; circumdants `\begin{...}...\end{...}`, en cas contrari aquestes etiquetes seran excloses. Si no s'especifica cap paràmetre, `inside` restarà establert a `false`. Si no es troba l'entorn de &latex;, es retornarà `Range.invalid()`, el qual es pot provar amb `Range.isValid()`.

    String document.environmentName();

  Retorna el nom de l'entorn de &latex; circumdant o una cadena buida.

    void document.removeEnvironment(bool inside = false);

  Elimina el text d'entorn de &latex; circumdant. Si el paràmetre `inside` és `false` (fals), es podrà eliminar tot el text d'entorn, incloses les etiquetes de &latex; circumdants `\begin{...}...\end{...}`, en cas contrari aquestes etiquetes seran excloses. Si no s'especifica cap paràmetre, `inside` restarà establert a `false`.

    void document.closeEnvironment();

  Insereix una etiqueta de tancament de l'entorn, si es troba un entorn de &latex; obert a la posició actual del cursor.

    void document.closeAllEnvironments();

  Insereix etiquetes de tancament a tots els entorns de &latex; oberts, si es troben a la posició actual del cursor.

    bool document.hasTexgroup();

  Retorna `true` (vertader) si es troba un grup de &latex; circumdant a la posició actual del cursor, d'altra manera `false` (fals).

    String document.texgroup(bool inside = true);

  Retorna el text del grup de &latex; circumdant. Si el paràmetre `inside` és `false` (fals), es retornarà el text d'aquest grup de &latex; incloent-hi les claus `{...}`, en cas contrari seran excloses. Si no s'especifica cap paràmetre, `inside` restarà establert a `false`. La cadena retornada restarà buida, si no es troba un grup de &latex; circumdant a la posició actual del cursor.

    Range document.texgroupRange(bool inside = true);

  Retorna l'interval del grup de &latex; circumdant Si el paràmetre `inside` és `false` (fals), l'interval inclourà les claus `{...}` circumdants, en cas contrari seran excloses. Si no s'especifica cap paràmetre, `inside` restarà establert a `false`. Si no es troba el grup, es retornarà `Range.invalid()`, el qual es pot provar amb `Range.isValid()`.

    void document.removeTexgroup(bool inside = true);

  Elimina el text del grup de &latex; circumdant. Si el paràmetre `inside` és `false` (fals), s'eliminarà tot en aquest grup de &latex;, incloses les claus circumdants `{...}`, en cas contrari seran excloses. Si no s'especifica cap paràmetre, `inside` restarà establert a `false`.

    bool document.hasMathgroup();

  Retorna `true` (vertader) si es troba un grup matemàtic de &latex; circumdant a la posició actual del cursor, d'altra manera `false` (fals).

    String document.mathgroup();

  Retorna el text del grup matemàtic de &latex; circumdant. La cadena retornada serà buida si no es troba cap grup matemàtic de &latex; circumdant a la posició actual del cursor.

    Range document.mathgroupRange();

  Retorna l'interval de l'entorn matemàtic de &latex; circumdant. Si no es troba cap grup matemàtic circumdant, es retornarà `Range.invalid()`, el qual es pot provar amb `Range.isValid()`.

    void document.removeMathgroup();

  Elimina el text del grup matemàtic de &latex; circumdant.

    String document.paragraph();

  Retorna el text del paràgraf de &latex; actual.

    Range document.paragraphRange();

  Retorna l'interval del paràgraf de &latex; circumdant.

    void document.removeParagraph();

  Elimina el text del paràgraf de &latex; actual.

    bool document.matchesAt(int línia, int columna, String text);
    bool document.matchesAt(Cursor cursor, String text);

  Retorna `true` (vertader), si el `text` donat coincideix a la posició del cursor corresponent, en cas contrari retornarà `false` (fals).

    bool document.startsWith(int línia, String patró, bool skipWhiteSpaces = true);

  Retorna `true` (vertader), si la línia comença amb patró, en cas contrari retornarà `false` (fals). L'argument skipWhiteSpaces controla si s'han d'ometre els espais en blanc davanters.

    bool document.endsWith(int línia, String patró, bool skipWhiteSpaces = true);

  Retorna `true` (vertader), si la línia acaba amb patró, en cas contrari retornarà `false` (fals). L'argument skipWhiteSpaces controla si s'han d'ometre els espais en blanc finals.

    int document.firstColumn(int línia);

  Retorna la primera columna que no està en blanc en la `línia` donada. Si només hi ha espais en blanc en la línia, el valor retornat serà `-1`.

    int document.lastColumn(int línia);

  Retorna la darrera columna que no està en blanc en la `línia` donada. Si només hi ha espais en blanc en la línia, el valor retornat serà `-1`.

    int document.prevNonSpaceColumn(int línia, int columna);
    int document.prevNonSpaceColumn(Cursor cursor);

  Retorna la columna no buida que conté caràcters no en blanc a partir de la posició donada del cursor i cercant cap enrere.

    int document.nextNonSpaceColumn(int línia, int columna);
    int document.nextNonSpaceColumn(Cursor cursor);

  Retorna la columna no buida que conté caràcters no en blanc a partir de la posició donada del cursor i cercant cap endavant.

    int document.prevNonEmptyLine(int línia);

  Retorna la línia següent no buida que conté caràcters no en blanc a la cerca cap enrere.

    int document.nextNonEmptyLine(int línia);

  Retorna la línia següent no buida que conté caràcters no en blanc a la cerca cap endavant.

    void document.gotoBeginEnv();

  Va al començament d'un entorn de &latex; circumdant.

    void document.gotoEndEnv();

  Va al final d'un entorn de &latex; circumdant.

    void document.gotoBeginTexgroup();

  Va al començament d'un grup de &latex; circumdant.

    void document.gotoEndTexgroup();

  Va al final d'un grup de &latex; circumdant.

    void document.gotoNextParagraph();

  Va a al següent paràgraf de &latex;.

    void document.gotoPrevParagraph();

  Va a l'anterior paràgraf de &latex;.

    void document.gotoNextSectioning();

  Va a la següent secció de &latex;.

    void document.gotoPrevSectioning();

  Va a l'anterior secció de &latex;.

    void document.gotoLine(int línia);

  Va a la `línia` donada.

    void document.insertChapter();

  Insereix una ordre `\chapter` (vegeu també `document.insertSection()`).

    void document.insertSection();

  Insereix una ordre `\section`. Com escollir l'entrada de menú LaTeX Seccionat secció que farà aparèixer un diàleg, des d'on podreu escollir el títol i una etiqueta opcional per aquesta ordre de seccionament. Diàleg: inserint una ordre «chapter» Diàleg: inserint una ordre «chapter»

    void document.insertSubsection();

  Insereix una ordre `\subsection` (vegeu també `document.insertSection()`).

    void document.insertSubsubsection();

  Insereix una ordre `\subsubsection` (vegeu també `document.insertSection()`).

    void document.insertParagraph();

  Insereix una ordre `\paragraph` (vegeu també `document.insertSection()`).

    void document.insertSubparagraph();

  Insereix una ordre `\subparagraph` (vegeu també `document.insertSection()`).

    void document.insertLabel();

  Insereix una ordre `\label`.

    void document.insertReference();

  Insereix una ordre `\ref`. Com escollir l'entrada de menú &latex;Referències ref que farà aparèixer un diàleg, des d'on podreu escollir entre les etiquetes ja definides, les quals s'enumeren en un quadre combinat. Diàleg: inserint una ordre «reference» Diàleg: inserint una ordre «reference»

    void document.insertPageref();

  Insereix una ordre `\pageref` (vegeu també `document.insertReference()`).

    void document.insertCitation();

  Insereix una ordre `\cite`.

    void document.insertIndex();

  Insereix una ordre `\index`.

    oid document.insertFootnote();

  Insereix una ordre `\footnote`.

    void document.comment();

  Insereix marcadors de comentari per fer un comentari de la selecció o línia actual.

    void document.uncomment();

  Elimina els marcadors de comentari de la selecció o línia actual.

    void document.uppercase();

  Canvia a majúscules el text seleccionat o la lletra després del cursor.

    void document.lowercase();

  Canvia el text seleccionat o la lletra després del cursor a minúscules.

    void document.capitalize();

  Capitalitza el text seleccionat o la paraula actual.

    void document.joinLines();

  Uneix les línies de la selecció actual. Dues línies de text successives sempre estaran separades amb un únic espai.

    void document.insertIntelligentNewline();

  Insereix un salt de línia intel·ligent (vegeu ).

    void document.insertIntelligentTabulator();

  Insereix un tabulador intel·ligent (vegeu ).

    void document.editBegin();

  Comença un grup d'edició per agrupar desfer/refer. Assegureu-vos de cridar sempre `editEnd()` tan aviat com crideu `editBegin()`. La crida `editBegin()` utilitza internament un comptador de referència, &ead;, aquesta crida es pot niar.

    void document.editEnd();

  Finalitza un grup d'edició. L'última crida de `editEnd()` (&ead;, una per a la primera crida de `editBegin()`) finalitza el pas d'edició.

    StringList document.labelList();

  Retorna totes les etiquetes definides com a `StringList`, les quals es poden utilitzar en &javascript; com una matriu de cadenes.

    StringList document.bibitemList();

  Retorna tots els «bibitem» definits com a `StringList`, els quals es poden utilitzar en &javascript; com una matriu de cadenes.

    void document.refreshStructure();

  Actualitza la vista de l'estructura (vegeu ).

### La API del &kile;

L'objecte global (variable) «`kile`» s'utilitza per manejar les interaccions de primer nivell amb el món exterior, missatge d'entrada i les interfícies de diàleg. Aquestes crides a l'API es divideixen en subobjectes per estructurar aquesta part de l'API per a la creació de scripts. Conceptualment, «`kile`» és semblant a un objecte «`window`» en l'API d'un navegador.

- `kile.alert`: quadres de missatge

- `kile.input`: obté l'entrada de l'usuari

- `kile.wizard`: crida un dels assistents del &kile;

- `kile.script`: obté informació sobre un script en execució

- `kile.file`: operacions amb fitxers, com ara la lectura o l'escriptura.

#### Alerta

    void kile.alert.information(String text, String subtítol);

  Mostra un diàleg informatiu. `text` serà la cadena del missatge i `subtítol` el títol del quadre de missatge. El títol per omissió serà el nom de l'script.

    void kile.alert.sorry(String text, String subtítol);

  Mostra un diàleg ho sento. `text` serà la cadena del missatge i `subtítol` el títol del quadre de missatge. El títol per omissió serà el nom de l'script.

    void kile.alert.error(String text, String subtítol);

  Mostra un diàleg d'error. `text` serà la cadena del missatge i `subtítol` el títol del quadre de missatge. El títol per omissió serà el nom de l'script.

    String kile.alert.question(String text, String subtítol);

  Mostra un diàleg de pregunta. `text` serà la cadena del missatge i `subtítol` el títol del quadre de missatge. El títol per omissió serà el nom de l'script. La cadena retornada serà `sí` o `no`.

    String kile.alert.warning(String text, String subtítol);

  Mostra un diàleg d'avís. `text` serà la cadena del missatge i `subtítol` el títol del quadre de missatge. El títol per omissió serà el nom de l'script. La cadena retornada serà `continua` o `cancel·la`.

#### Entrada

    String kile.input.getListboxItem(String subtítol, String etiqueta, StringList llista);

  Funció perquè l'usuari seleccioni un element d'una llista, que es mostrarà com un quadre de llista. `subtítol` serà el text que es mostrarà a la barra de títol, `etiqueta` serà el text que apareixerà com a etiqueta per a la llista i `llista` serà la llista de cadenes que s'inseriran a la llista.

    String kile.input.getComboboxItem(String subtítol, String etiqueta, StringList llista);

  Funció perquè l'usuari seleccioni un element d'una llista, que es mostrarà com un quadre combinat. `subtítol` serà el text que es mostrarà a la barra de títol, `etiqueta` serà el text que apareixerà com a etiqueta per a la llista i `llista` serà la llista de cadenes que s'inseriran a la llista.

    String kile.input.getText(String subtítol, String etiqueta);

  Funció per obtenir una cadena de l'usuari. `subtítol` serà el text que es mostrarà a la barra de títol i `etiqueta` serà el text que apareixerà com a etiqueta per editar la línia.

    String kile.input.getLatexCommand(String subtítol, String etiqueta);

  Funció per obtenir una ordre de &latex; de l'usuari. Això vol dir que només es permeten lletres majúscules i minúscules. `subtítol` serà el text que es mostrarà a la barra de títol i `etiqueta` serà el text que apareixerà com a etiqueta per editar la línia.

    int kile.input.getInteger(String subtítol, String etiqueta, int min = ENTER_MÍN, int max = ENTER_MÀX);

  Funció per obtenir un nombre enter de l'usuari. `subtítol` serà el text que es mostrarà a la barra de títol i `etiqueta` serà el text que apareixerà com a etiqueta per al botó de selecció de valors. `min` i `max` són els valors mínims i màxims permesos que l'usuari podrà triar. Els valors per omissió seran `ENTER_MÍN` i `ENTER_MÀX`.

    int kile.input.getPosInteger(String subtítol, String etiqueta, int min = 1, int max = ENTER_MÀX);

  Funció per obtenir un enter positiu de l'usuari. `subtítol` serà el text que es mostrarà a la barra de títol i `etiqueta` serà el text que apareixerà com a etiqueta per al botó de selecció de valors. `min` i `max` són els valors mínims i màxims permesos que l'usuari podrà triar. Els valors per omissió seran `1` i `ENTER_MÀX`.

#### Assistent

    void kile.wizard.tabular();

  Crida a l'assistent tabular, el qual us ajudarà a escriure un entorn tabular (vegeu ).

    void kile.wizard.array();

  Crida a l'assistent de Matriu, el qual us ajudarà a escriure un entorn de matriu (vegeu ).

    void kile.wizard.tabbing();

  Crida a l'assistent de Tabulació, el qual us ajudarà a escriure un entorn de tabulació (vegeu ).

    void kile.wizard.floatEnvironment();

  Crida a l'assistent d'Elements flotants, el qual us ajudarà a inserir elements flotants (vegeu ).

    void kile.wizard.mathEnvironment();

  Crida a l'assistent Matemàtica, el qual us ajudarà a inserir entorns matemàtics (vegeu ).

    void kile.wizard.postscript();

  Crida a l'assistent Eines Postscript, el qual us pot ajudar a manipular o reorganitzar els documents PostScript (vegeu ).

#### Script

    String kile.script.name();

  Retorna el nom base d'un script en execució (sense el camí i l'extensió).

    String kile.script.caption();

  Retorna una cadena, la qual es podrà utilitzar com un subtítol dels quadres d'alerta. S'assembla a `Script: nom_script.js`.

#### Fitxer

    Object kile.file.read(String nom_fitxer);

  Llegeix el contingut d'un fitxer de text. S'utilitza com

  Exemple: `var res = kile.file.read("camí/al/fitxer.txt");`

  El valor retornat de `res` serà un objecte (millor: un mapa), amb tres propietats:

  - estat: Indica el codi d'estat de l'operació, el qual pot ser 0 (sense error), 1 (accés fallit) o 2 (accés denegat). Per tant, si no hi ha errors, el valor de `res.status` o `res["status"]` serà 0.

  - resultat: Conté el text del fitxer donat.

  - missatge: Contindrà un missatge d'error si es produeix un error.

    Object kile.file.read();

  El mateix que `read(nom_fitxer)`, però sense donar cap fitxer. Apareixerà un diàleg que us permetrà seleccionar el fitxer a llegir.

    Object kile.file.write(String nom_fitxer, String text);

  Escriu el text especificat en un fitxer. S'utilitza com segueix

  Exemple: `var res = kile.file.write("camí/al/fitxer.txt","Algun text...");`

  El valor retornat de `res` serà un objecte (millor: un mapa) amb dues propietats: `estat` i `missatge` (vegeu `read()` per més informació).

    Object kile.file.write(String text);

  El mateix que `write(nom_fitxer,text)`, però sense donar cap fitxer. Apareixerà un diàleg per triar un nom de fitxer.

    String kile.file.getOpenFileName(String iniciDirectori, String filtre);

  Crea un diàleg de manera de fitxer i retornarà el nom del fitxer seleccionat, o una cadena buida si no s'ha triat cap fitxer. Tingueu en compte que amb aquest mètode l'usuari haurà de seleccionar un nom de fitxer existent.

  Paràmetres:

  - startDir: Directori d'inici del diàleg obert.

  - filter: Un intèrpret d'ordres estàndard o un filtre de tipus &MIME; que indicarà el tipus de fitxers a mostrar. Referiu-vos a la documentació de KFileDialog per a més informació sobre aquest paràmetre.

  Tots dos paràmetres són opcionals. Si ometeu `filtre`, es mostraran tots els fitxers. Si, a més, ometeu `iniciDirectori`, el diàleg tindrà el directori del document actual com a punt de partida.

    String kile.file.getSaveFileName(String iniciDirectori, String filtre);

  Crea un diàleg de manera de fitxer i retornarà el nom del fitxer seleccionat, o una cadena buida si no s'ha triat cap fitxer. Tingueu en compte que amb aquest mètode l'usuari no haurà de seleccionar un nom de fitxer existent. Vegeu `getOpenFileName()` per a una explicació dels paràmetres.

## Exemples

Alguns exemples poden ajudar a entendre com utilitzar l'API per a crear scripts. Aquests exemples i alguns més es troben al directori per a crear scripts del &kile;: `KILE_APP_DIR/scripts/`. Cada script conté una petita descripció.

### Exemple 1: substituir el nom d'entorn

Substitueix un entorn de &latex; circumdant amb un altre, on la posició relativa del cursor no serà canviada. `\begin{abc}...\end{abc}`, per exemple es pot canviar a `\begin{xyz}...\end{xyz}`.

    var range = document.environmentRange(false);
    if ( range.isValid() ) {
            var envname = kile.input.getLatexCommand("Introduïu l'entorn","Nou nom de l'entorn:");
            if ( envname != '' ) {
                    replaceEnvCommand(envname,range);
            }
    }
    else {
            kile.alert.sorry("No s'ha trobat un entorn de LaTeX circumdant.");
    }

    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();
            }
    }

### Exemple 2: substituir una ordre de tipus de lletra de &latex;

Substitueix una ordre de tipus de lletra de &latex; circumdant amb una altra ordre de tipus de lletra, quan el cursor està situat dins del grup de TeX. La posició relativa del cursor no serà canviada. `\textbf{abc}`, per exemple, es pot canviar a `\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("No s'ha trobat un grup de TeX circumdant.");
    }

    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",
                                                        "Tria l'ordre de tipus de lletra:",buildCmdList(cmd));
                            if ( newcommand != "" ) {
                                    document.replaceText(cmdRange,newcommand);
                                    c.column = c.column - (cmd.length - newcommand.length);
                            }
                    }
    /                view.setCursorPosition(c);
            }
            else {
                    kile.alert.sorry("No s'ha trobat una ordre de tipus de lletra circumdant.");
            }
            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;
    }

### Exemple 3: envoltar el text seleccionat

Envolta el text seleccionat amb una ordre de TeX, on la posició relativa del cursor no serà canviada. `abc` per exemple es podrà canviar a `\texcommand{abc}`.

    var range = view.selectionRange();

    if ( range.isValid() ) {
            var cmd = kile.input.getLatexCommand("Tria","Tria una ordre de LaTeX circumdant:");
            if ( cmd != "" ) {
                    surroundTexCommand("\\"+cmd,range);
            }
    }
    else {
            kile.alert.sorry("No s'ha trobat una selecció.");
    }

    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();
    }