# Uso de scripts

## Uso de scripts en &kile;

La función de uso de scripts de &kile; permite la ejecución de código ECMAScript, ampliamente conocido como &javascript;. Encontrará muchos tutoriales, que proporcionan información sobre los objetos (variables), las funciones y las propiedades soportados por &javascript;.

El soporte para la ejecución de scripts se puede activar en el diálogo de configuración de &kile;: Preferencias Configurar Kile… Kile Ejecución de scripts. Activar o desactivar el soporte para la ejecución de scripts Activar o desactivar el soporte para la ejecución de scripts

Al activar la ejecución de scripts, aparece un nuevo panel para la gestión de scripts en la barra lateral, en el que se puede administrar los scripts: El panel de administración de scripts de la barra lateral El panel de administración de scripts de la barra lateral

Esta ventana contiene seis iconos, que permiten realizar diversas tareas:

- Ejecutar el script seleccionado.

- Crear un script nuevo.

- Abrir el script seleccionado en el editor.

- Configurar una secuencia de teclas para el script seleccionado.

- Eliminar una secuencia de teclas asignada.

- Actualizar la lista de los scripts disponibles, que se encuentran en `$`KDEDIR`/share/apps/kile/scripts/`.

## Ejecutar un script

Un script se puede ejecutar de tres maneras diferentes:

1. Seleccione el script deseado y haga clic en el botón Ejecutar del lado izquierdo de la ventana de administración de scripts.

   Ejecución de scripts: botón ejecutar Ejecución de scripts: botón ejecutar

2. Use un atajo de teclado.

   Ejecución de scripts: atajo de teclado Ejecución de scripts: atajo de teclado

   Puede asignar un atajo de teclado a un script utilizando el botón Configurar de la ventana de administración de scripts.

   Ejecución de scripts: diálogo de configuración de secuencia Ejecución de scripts: Diálogo de configuración de secuencia

3. Utilice una secuencia de teclas del editor. El script se ejecutará, si teclea la secuencia de teclas asignada en el editor.

   Ejecución de scripts: secuencia de teclas del editor Ejecución de scripts: secuencia de teclas del editor

   Este método se puede extender a un tipo bastante sofisticado de completado de código. Vamos a asumir que se ha escrito un script, que simplemente introduce el comando &latex; `\textbf{}` en el documento actual.

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

   Si ahora se teclea la secuencia de teclas asignada `bfx` en el documento de texto, automáticamente se borrará la secuencia de teclas y se ejecutará el script. El script introducirá `\textbf{}` y el cursor quedará colocado entre los dos corchetes.

   Ejecución de scripts: escribir una secuencia de teclas del editor Ejecución de scripts: escribir una secuencia de teclas del editor

   Un método cómodo y potente de completado de código.

## Referencia de la API

El API de creación de scripts presentada en este documento está disponible en todos los scripts. Antes de que se cargue el contenido de un script, &kile; añade varios prototipos y funciones al contexto de ejecución de scripts. Esta API de conveniencia contiene prototipos como cursores e intervalos de texto y está ubicada en la carpeta `KILE_APP_DIR/script-plugins/`.

Los scripts de &kile; son ligeramente diferentes a los scripts de &kate;, que utilizan otro diseño, puesto que también pueden iniciarse desde la línea de ordenes. Pero todas las funciones de la API de creación de scripts de &kate; también están disponibles en la API de creación de scripts de &kile;, por lo que portar código &javascript; de &kate; a &kile; debería ser muy fácil. Pero como &kile; es un editor &latex; muy rico en características, su propia API de creación de scripts ofrece muchas más posibilidades que la de &kate;.

Observación: La descripción de las llamadas a la API, que también están disponibles para los scripts de &kate;, han sido tomadas de la documentación de &kate;.

### Funciones globales

Esta sección lista las funciones globales.

    void debug(String texto);

- Imprime `texto` en `stdout` en la consola. El texto imprimido es coloreado para distinguirlo del otros datos de depuración mostrados.

### El prototipo cursor

Como &kile; es un editor de texto, toda la API de creación de scripts se basa en cursores e intervalos siempre que es posible. Un cursor es una tupla simple `(linea, columna)` que representa una posición de texto en el documento.

    Cursor();

- Constructor: Devuelve un cursor en la posición `(0,0)`.

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

    Cursor(int linea, int columna);

- Constructor: Devuelve un cursor en la posición (linea,columna).

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

    Cursor(Cursor otro);

- Constructor de copia: Devuelve una copia del cursor `otro`.

  Ejemplo: `var copia = new Cursor(otro);`

    Cursor Cursor.clone();

- Devuelve un clon del cursor

  Ejemplo: `var clon = cursor.clone();`

    bool Cursor.isValid();

- Comprueba si el cursor es válido. El cursor no es válido si la línea y/o la columna tiene un valor de `-1`.

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

    Cursor Cursor.invalid();

- Devuelve un cursor inválido nuevo ubicado en `(-1,-1)`.

  Ejemplo: `var cursorInvalido = cursor.invalid();`

    int Cursor.compareTo(Cursor otro);

- Compara este cursor con el cursor `otro`. Devuelve

  - `-1`, si el cursor está ubicado antes del cursor `otro`,

  - `0`, si ambos cursores son iguales y

  - `+1`, si el cursor está ubicado después del cursor `otro`,

    bool Cursor.equals(Cursor otro);

- Devuelve `true`, si este cursor y el cursor `otro` son iguales, en caso contrario devuelve `falso`.

    String Cursor.toString();

- Devuelve el cursor como un string con la forma `Cursor(linea,columna)`.

### El prototipo intervalo

Como &kile; es un editor de texto, toda la API de creación de scripts se basa en cursores e intervalos siempre que es posible. Un cursor es una tupla simple `(linea, columna)` que representa una posición de texto en el documento, un intervalo abarca el texto comprendido desde una posición de inicio del cursor a una posición de fin del cursor.

    Range();

- Constructor: Llamar a `new Range()` devuelve el intervalo `(0,0) - (0,0)`.

    Range(Cursor inicio, Cursor fin);

- Constructor: Llamar a `new Range(`inicio`, `fin`)` devuelve el intervalo comprendido desde el cursor `inicio` al cursor `fin`.

    Range(int lineaDeInicio, int columnaDeInicio, int lineaDeFin, int columnaDeFin);

- Constructor: Llamar a `new Range(`lineaDeInicio`,`columnaDeInicio`,`lineaDeFin`, `columnaDeFin`)` devuelve el intervalo comprendido desde (`lineaDeInicio`, `columnaDeInicio`) a (`lineaDeFin`, `columnaDeFin`).

    Range(Range otro);

- Constructor de copia: Devuelve una copia del intervalo `otro`.

    Range Range.clone();

- Devuelve un clon del intervalo.

  Ejemplo: `var clon = range.clone();`

    bool Range.isValid();

- Devuelve `true`, si tanto el cursor de inicio como el de fin son válidos, en caso contrario devuelve `false`.

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

    bool Range.invalid();

- Devuelve el intervalo de (-1,-1) a (-1,-1).

    bool Range.contains(Cursor cursor);

- Devuelve `true`, si este intervalo contiene la posición cursor, en caso contrario devuelve `false`.

    bool Range.contains(Range otro);

- Devuelve `true`, si este intervalo contiene el intervalo `otro`, en caso contrario devuelve `false`.

    bool Range.containsColumn(int columna);

- Devuelve `true`, si `columna` está en el intervalo semiabierto `[inicio.columna, fin.columna]`, en caso contrario devuelve `false`.

    bool Range.containsLine(int linea);

- Devuelve `true`, si `linea` está en el intervalo semiabierto `[inicio.línea, fin.línea]`, en caso contrario devuelve `false`.

    bool Range.overlaps(Range otro);

- Devuelve `true`, si este intervalo y el intervalo `otro` comparten una región común, en caso contrario devuelve `false`.

    bool Range.overlapsLine(int linea);

- Devuelve `true`, si `linea` está en el intervalo `[inicio.linea, fin.linea]`, en caso contrario devuelve `false`.

    bool Range.overlapsColumn(int columna);

- Devuelve `true`, si `columna` está en el intervalo `[inicio.columna, fin.columna]`, en caso contrario devuelve `false`.

    bool Range.equals(Range otro);

- Devuelve `true`, si este intervalo y el parámetro Range `otro` son iguales, en caso contrario devuelve `false`.

    String Range.toString();

- Devuelve el intervalo como una cadena de texto de la forma `Range(Cursor(linea,columna) - Cursor(linea-columna))`.

### El API «View»

Siempre que un script está siendo ejecutado, hay un objeto (variable) global `view` que representa la vista activa actual del editor. Todas las funciones de `view` trabajan con posiciones del cursor o texto seleccionado. La siguiente es una lista de todas las funciones disponibles de `view`.

    void view.backspace();

- Programáticamente efectúa la acción equivalente a pulsar la tecla de retroceso.

    Cursor view.cursorPosition();

- Devuelve la posición actual del cursor en la vista.

    void view.setCursorPosition(int linea, int columna);
    void view.setCursorPosition(Cursor cursor);

- Establece la posición actual del cursor a el par `linea`, `columna` o al `cursor` dado.

    void view.cursorLeft();

- Mueve el cursor una posición hacia atrás en el texto.

    void view.cursorRight();

- Mueve el cursor una posición hacia delante en el texto.

    void view.cursorUp();

- Mueve el cursor una línea hacia arriba en el documento.

    void view.cursorDown();

- Mueve el cursor una línea hacia abajo en el documento.

    int view.cursorLine();

- Devuelve la línea en la que se encuentra actualmente el cursor.

    int view.cursorColumn();

- Devuelve la columna en la que se encuentra actualmente el cursor.

    void view.setCursorLine(int linea);

- Establece como línea del cursor la `linea` dada como parámetro.

    void view.setCursorColumn(int columna);

- Establecer como columna del cursor la `columna` dada como parámetro.

    Cursor view.virtualCursorPosition();

- Obtiene la posición virtual actual del cursor. Virtual significa que el carácter tabulador (TAB) cuenta por varios caracteres, según lo haya configurado el usuario (por ejemplo, un TAB puede ser 8 espacios). La posición virtual del cursor proporciona acceso a los valores visibles del usuario de la posición actual del cursor.

    bool view.hasSelection();

- Devuelve `true`, si la vista tiene texto seleccionado, en caso contrario devuelve `false`.

    String view.selectedText();

- Devuelve el texto seleccionado. Si no hay texto seleccionado, devuelve un string vacío.

    Range view.selectionRange();

- Devuelve el intervalo de texto seleccionado. Si no hay texto seleccionado el intervalo devuelto no es válido.

    void view.setSelection(Range intervalo);

- Modifica el texto seleccionado por el `intervalo` dado.

    void view.selectAll();

- Selecciona todo el texto del documento.

    void view.clearSelection();

- Borra la selección de texto sin eliminar el texto.

    void view.removeSelectedText();

- Elimina el texto seleccionado. Si la vista no tiene ningún texto seleccionado, entonces esta función no hace nada.

    void view.selectLine();

- Selecciona el texto de la línea actual.

    void view.selectLine(int linea);

- Selecciona el texto de la `linea` dada.

    void view.selectLines(int desde, int hasta);

- Selecciona todo el texto comprendido entre la línea `desde` y la línea `hasta`.

    void view.selectWord();

- Selecciona la palabra actual. Si no se encuentra ninguna palabra en la posición actual del cursor, no se hace nada.

    void view.selectLatexCommand();

- Selecciona la orden &latex; actual. Si no se encuentra ninguna orden en la posición actual del cursor, no se hace nada.

    void view.selectEnvironment(bool interior = false);

- Selecciona todo el texto del entorno &latex; actual. Si `interior` es `false`, se seleccionará el texto del entorno, además de las etiquetas &latex; de apertura y cierre `\begin{…}…\end{…}`; en caso contrario, solo se seleccionará el texto interior, pero no las etiquetas de apertura y cierre. Si no se pasa ningún parámetro, `interior` se establece a `false` de manera predeterminada.

    void view.selectTexgroup(bool interior = true);

- Selecciona el texto del grupo &latex; actual. Si `interior` es `true`, solo se seleccionará el texto del grupo sin las llave de apertura y cierre. Si no se pasa ningún parámetro `interior` se establece a `true`.

    void view.selectMathgroup();

- Selecciona el texto del grupo matemático actual.

    void view.selectParagraph(bool lineasCompletas = true);

- Selecciona todo el texto del párrafo &latex; actual. Si `lineasCompletas` es `true`, la primera y la última línea del párrafo se incluirán en la selección completamente (incluyendo el carácter de fin de línea); en caso contrario, la selección solo contendrá los caracteres que no sean espacios en blanco.

### La API «Document»

Siempre que un script está siendo ejecutado, hay un objeto (variable) global `document` que representa el documento activo actual. La siguiente es una lista de todas las funciones disponibles de `document`.

    void document.insertText(String texto);

- Inserta el `texto` en la posición actual del cursor.

    void document.insertText(int linea, int columna, String texto);
    void document.insertText(Cursor cursor, String texto);

- Inserta el `texto` en la posición del cursor dado.

    bool document.removeText(int lineaComienzo, int columnaComienzo, int lineaFin, int columnaFin);
    bool document.removeText(Cursor desde, Cursor hasta);
    bool document.removeText(Range intervalo);

- Elimina el texto que se encuentra en el intervalo dado. Devuelve `true` en caso de éxito, o `false`, si el documento está en modo de solo lectura.

    bool document.replaceText(Range intervalo, String texto);

- Reemplaza el texto del intervalo dado con el texto especificado.

    int document.lines();

- Devuelve el número de líneas del documento.

    int document.length();

- Devuelve el número de caracteres del documento.

    Range document.documentRange();

- Devuelve un intervalo que abarca todo el documento.

    Cursor document.documentEnd();

- Devuelve la posición actual del cursor de final del documento.

    String document.text();

- Devuelve todo el contenido del documento en un único string de texto. Las líneas nuevas se marcan mediante el carácter de línea nueva `\n`.

    String document.text(int lineaDesde, int columnaDesde, int lineaHasta, int columnaHasta);
    String document.text(Cursor desde, Cursor hasta);
    String document.text(Range intervalo);

- Devuelve el texto que se encuentra en el intervalo indicado. Se recomienda utilizar las versiones basadas en los parámetros «Cursor» y «Range» para una mejor legibilidad del código fuente.

    bool document.setText(String texto);

- Establece todo el texto del documento.

    bool document.clear();

- Elimina todo el texto del documento.

    String document.line();

- Devuelve la línea de texto actual como un string.

    String document.line(int linea);

- Devuelve la línea de texto indicada como un string. Si la línea solicitada está fuera de los límites del documento se devuelve un string vacío.

    int document.lineLength();

- Devuelve la longitud de la línea actual.

    int document.lineLength(int linea);

- Devuelve la longitud de `linea`.

    bool document.insertLine(String s);

- Inserta el texto en la línea actual. Devuelve `true` en caso de éxito, o `false`, si el documento está en modo de solo lectura o si la línea está fuera de los límites del documento.

    bool document.insertLine(int linea, String s);

- Inserta texto en la línea indicada. Devuelve `true` en caso de éxito, o `false`, si el documento está en modo de solo lectura o la línea está fuera de los límites del documento.

    bool document.removeLine();

- Elimina la línea de texto actual. Devuelve `true` en caso de éxito, o `false`, si el documento está en modo de solo lectura.

    bool document.removeLine(int linea);

- Elimina la línea de texto indicada. Devuelve `true` en caso de éxito, o `false`, si el documento está en modo de solo lectura o la línea está fuera de los límites del documento.

    bool document.replaceLine(String texto);

- Reemplaza el texto de la línea actual con el texto especificado.

    bool document.replaceLine(int linea, String texto);

- Reemplaza el texto de la línea indicada con el texto especificado.

    bool document.truncateLine();

- Trunca la línea actual en la columna o posición de cursor dados. Devuelve `true` en caso de éxito, o `false` si la línea dada está fuera de los límites del documento.

    bool document.truncate(int linea, int columna);
    bool document.truncate(Cursor cursor);

- Trunca la línea indicada en la columna o posición de cursor dados. Devuelve `true` en caso de éxito, o `false` si la línea indicada está fuera de los límites del documento.

    String document.word();

- Devuelve la palabra que hay en la posición actual del cursor. Si no se encuentra ninguna palabra en la posición del cursor, se devuelve una cadena vacía.

    String document.wordAt(int linea, int columna);
    String document.wordAt(Cursor cursor);

- Devuelve la palabra que hay en la posición de cursor indicada. Si no se encuentra ninguna palabra en esta posición de cursor, se devuelve una cadena vacía.

    Range document.wordRange();

- Devuelve el intervalo de la palabra que se encuentra en la posición de cursor dada. Si no hay ninguna palabra, se devuelve `Range.invalid()`, que puede ser verificado con `Range.isValid()`.

    String document.latexCommand();

- Devuelve la orden &latex; que se encuentra en la posición actual del cursor. Si no hay ninguna orden en esta posición de cursor, se devuelve una cadena vacía.

    String document.latexCommandAt(int linea, int columna);
    String document.latexCommandAt(Cursor cursor);

- Devuelve la orden &latex; que se encuentra en la posición de cursor indicada. Si no hay ninguna orden en esta posición de cursor, se devuelve una cadena vacía.

    Range document.latexCommandRange();

- Devuelve el intervalo de la orden &latex; que se encuentra en la posición de cursor indicada. Si no hay ninguna orden &latex;, se devuelve `Range.invalid()`, que se puede verificar con `Range.isValid()`.

    String document.charAt(int linea, int columna);
    String document.charAt(Cursor cursor);

- Devuelve el carácter que se encuentra en la posición de cursor indicada.

    String document.firstChar(int linea);

- Devuelve el primer carácter que hay en la `linea` indicada y que no es un espacio en blanco. El primer carácter está en la columna 0. Si la línea está vacía o si solo contiene espacios en blanco, se devuelve un string vacío.

    String document.lastChar(int linea);

- Devuelve el último carácter que hay en la `linea` indicada y que no es un espacio en blanco. Si la línea está vacía o si solo contiene espacios en blanco, se devuelve un string vacío.

    bool document.isSpace(int linea, int columna);
    bool document.isSpace(Cursor cursor);

- Devuelve `true`, si el carácter que se encuentra en la posición de cursor indicada es un espacio en blanco, en caso contrario devuelve `false`.

    void document.insertBullet();

- Inserta una viñeta de &kile;. Recuerde que puede saltar fácilmente a la viñeta siguiente o anterior. Esto también resaltará esta viñeta de modo que se borrará automáticamente, cuando teclee la primera letra.

    void document.nextBullet();

- Salta a la siguiente viñeta del texto si hay alguna.

    void document.previousBullet();

- Salta a la anterior viñeta del texto si hay alguna.

    bool document.hasEnvironment();

- Devuelve `true` si se encuentra algún entorno de &latex; circundante, en caso contrario devuelve `false`.

    String document.environment(bool interior = false);

- Devuelve todo el texto del entorno &latex; circundante. Si `interior` es `false`, se devolverá el texto del entorno incluyendo a las etiquetas &latex; de apertura y cierre `\begin{…}…\end{…}`, en caso contrario, las etiquetas no se incluyen en el texto devuelto. Si no se indica ningún parámetro, `interior` se establece a `false`. Si no se encuentra ningún entorno, se devuelve un string vacío.

    Range document.environmentRange(bool interior = false);

- Devuelve el intervalo del entorno &latex; circundante. Si `interior` es `false`, se devolverá el intervalo que incluye a las etiquetas &latex; de apertura y cierre `\begin{…}…\end{…}`, en caso contrario no se incluyen las etiquetas. Si no se indica ningún parámetro, `interior` se establece a `false`. Si no se encuentra ningún entorno, se devuelve `Range.invalid()` que se puede verificar con `Range.isValid()`.

    String document.environmentName();

- Devuelve el nombre del entorno &latex; circundante o un string vacío.

    void document.removeEnvironment(bool interior = false);

- Elimina el texto del entorno &latex; circundante. Si `interior` es `false`, se eliminará el texto del entorno incluyendo a las etiquetas &latex; de apertura y cierre `\begin{…}…\end{…}`, en caso contrario las etiquetas no se eliminan. Si no se indica ningún parámetro, `interior` se establece a `false`.

    void document.closeEnvironment();

- Inserta una etiqueta de cierre de entorno, si se encuentra un entorno &latex; abierto en la posición actual del cursor.

    void document.closeAllEnvironments();

- Inserta etiquetas de cierre de entorno para todos los entornos &latex; abiertos, que se encontraron en la posición actual del cursor.

    bool document.hasTexgroup();

- Devuelve `true` si se encuentra un grupo &latex; circundante en la posición actual del cursor, sino `false`.

    String document.texgroup(bool interior = true);

- Devuelve el texto del grupo &latex; circundante. Si `interior` es `false`, se devolverá el texto de este grupo &latex; incluyendo los corchetes de apertura y cierre `{…}`, sino sin ellos. Si no se indica ningún parámetro, `interior` se establece a `false`. Si no se encuentra ningún grupo &latex; circundante en la posición actual del cursor, se devuelve un string vacío.

    Range document.texgroupRange(bool interior = true);

- Devuelve el intervalo del grupo &latex; circundante. Si `interior` es `false`, se devolverá el intervalo que incluye los corchetes de apertura y cierre `{…}`, sino sin ellos. Si no se indica ningún parámetro, `interior` se establece a `false`. Si no se encuentra ningún grupo, se devuelve `Range.invalid()` que se puede verificar con `Range.isValid()`.

    void document.removeTexgroup(bool interior = true);

- Elimina el texto del grupo &latex; circundante. Si `interior` es `false`, se eliminará el texto de este grupo &latex; incluyendo los corchetes de apertura y cierre `{…}`, sino sin ellos. Si no se indica ningún parámetro, `interior` se establece a `false`.

    bool document.hasMathgroup();

- Devuelve `true` si se encuentra un grupo matemático de &latex; circundante en la posición actual del cursor, sino devuelve `false`.

    String document.mathgroup();

- Devuelve el texto del grupo matemático &latex; circundante. Si no se encuentra ningún grupo matemático &latex; circundante en la posición actual del cursor, se devuelve un string vacío.

    Range document.mathgroupRange();

- Devuelve el intervalo del grupo matemático &latex; circundante. Si no existe ningún grupo matemático circundante, se devuelve `Range.invalid()`, que se puede verificar con `Range.isValid()`.

    void document.removeMathgroup();

- Elimina el texto del grupo matemático &latex; circundante.

    String document.paragraph();

- Devuelve el texto del párrafo &latex; actual.

    Range document.paragraphRange();

- Devuelve el intervalo del párrafo &latex; circundante.

    void document.removeParagraph();

- Elimina el texto del párrafo &latex; actual.

    bool document.matchesAt(int linea, int columna, String texto);
    bool document.matchesAt(Cursor cursor, String texto);

- Devuelve `true`, si el `texto` indicado coincide con el que se encuentra en la posición de cursor correspondiente, en caso contrario devuelve `false`.

    bool document.startsWith(int linea, String patron, bool saltarEspaciosEnBlanco = true);

- Devuelve `true`, si la línea comienza con el `patron`, en caso contrario devuelve `false`. El argumento `saltarEspaciosEnBlanco` controla si se ignoran los espacios en blando iniciales.

    bool document.endsWith(int linea, String patron, bool saltarEspaciosEnBlanco = true);

- Devuelve `true`, si la línea finaliza con `patron`, en caso contrario devuelve `false`. El argumento `saltarEspaciosEnBlanco` controla si se ignoran los espacios en blanco finales.

    int document.firstColumn(int linea);

- Devuelve la primera columna que no es un espacio en blanco de la `linea` indicada. Si solo hay espacios en blanco en la línea, el valor devuelto es `-1`.

    int document.lastColumn(int linea);

- Devuelve la última columna que no es un espacio en blanco de la `linea` indicada. Si solo hay espacios en blanco en la línea, el valor devuelto es `-1`.

    int document.prevNonSpaceColumn(int linea, int columna);
    int document.prevNonSpaceColumn(Cursor cursor);

- Devuelve la columna sin caracteres de espacio en blanco comenzando en la posición de cursor indicada y buscando hacia atrás.

    int document.nextNonSpaceColumn(int linea, int columna);
    int document.nextNonSpaceColumn(Cursor cursor);

- Devuelve la columna sin caracteres de espacio en blanco comenzando en la posición de cursor indicada y buscando hacia delante.

    int document.prevNonEmptyLine(int linea);

- Devuelve la siguiente línea no vacía que no contiene caracteres de espacio en blanco, buscando hacia atrás.

    int document.nextNonEmptyLine(int linea);

- Devuelve la siguiente línea no vacía que no contiene caracteres de espacio en blanco, buscando hacia delante.

    void document.gotoBeginEnv();

- Va al inicio de un entorno &latex; circundante.

    void document.gotoEndEnv();

- Va al final de un entorno &latex; circundante.

    void document.gotoBeginTexgroup();

- Va al inicio de un grupo &latex; circundante.

    void document.gotoEndTexgroup();

- Va al final de un grupo &latex; circundante.

    void document.gotoNextParagraph();

- Va al siguiente párrafo &latex;.

    void document.gotoPrevParagraph();

- Va al párrafo &latex; anterior.

    void document.gotoNextSectioning();

- Va a la siguiente sección &latex;.

    void document.gotoPrevSectioning();

- Va a la sección &latex; anterior.

    void document.gotoLine(int linea);

- Va a la `linea` indicada.

    void document.insertChapter();

- Inserta una orden `\chapter` (consultar también `document.insertSection()`).

    void document.insertSection();

- Inserta una orden `\section`. Al igual que cuando se selecciona la entrada de menú LaTeX Secciones section aparecerá un diálogo, en el que puede seleccionar el título y una etiqueta opcional para esta orden de sección. Diálogo: insertar orden chapter Diálogo: insertar orden chapter

    void document.insertSubsection();

- Inserta una orden `\subsection` (consulte también `document.insertSection()`).

    void document.insertSubsubsection();

- Inserta una orden `\subsubsection` (consulte también `document.insertSection()`).

    void document.insertParagraph();

- Inserta una orden `\paragraph` (consulte también `document.insertSection()`).

    void document.insertSubparagraph();

- Inserta una orden `\subparagraph` (consulte también `document.insertSection()`).

    void document.insertLabel();

- Inserta una orden `\label`.

    void document.insertReference();

- Inserta una orden `\ref`. Al igual que cuando se selecciona la entrada de menú &latex;Referencias ref aparecerá un diálogo, en el que se puede elegir alguna de las etiquetas ya definidas, que se listan en una lista despegable. Diálogo: insertar una orden referencia Diálogo: insertar una orden referencia

    void document.insertPageref();

- Inserta una orden `\pageref` (consulte también `document.insertReference()`).

    void document.insertCitation();

- Inserta una orden `\cite`.

    void document.insertIndex();

- Inserta una orden `\index`.

    void document.insertFootnote();

- Inserta una orden `\footnote`.

    void document.comment();

- Inserta las marcas de comentario para convertir a la selección o a la línea actual en un comentario.

    void document.uncomment();

- Elimina las marcas de comentario de la selección o línea actual.

    void document.uppercase();

- Pone el texto seleccionado o la letra que se encuentra a continuación de cursor en mayúsculas.

    void document.lowercase();

- Pone el texto seleccionado o la letra que se encuentra a continuación de cursor en minúsculas.

    void document.capitalize();

- Capitaliza el texto seleccionado o la palabra actual.

    void document.joinLines();

- Une las líneas de la selección actual. Dos líneas de texto sucesivas siempre están separadas por un único espacio.

    void document.insertIntelligentNewline();

- Inserta una línea nueva inteligente (consulte editing_smartnewline).

    void document.insertIntelligentTabulator();

- Inserta un tabulador inteligente (consulte editing_tabulator).

    void document.editBegin();

- Inicia un grupo de edición para agrupar operaciones de deshacer/rehacer. Asegúrese de llamar a `editEnd()` siempre tantas veces como llame a `editBegin()`. La llamada a `editBegin()` utiliza internamente un contador de referencia, es decir, esta llamada se puede anidar.

    void document.editEnd();

- Finaliza un grupo de edición. La última llamada de `editEnd()` (es decir, la correspondiente a la primera llamada a `editBegin()` finaliza el paso de edición.

    StringList document.labelList();

- Devuelve todas las etiquetas como una `StringList`, que se puede utilizar en &javascript; como un array de strings.

    StringList document.bibitemList();

- Devuelve todos los elementos de bibliografía definidos como una `StringList`, que se puede utilizar en &javascript; como un array de strings.

    void document.refreshStructure();

- Actualiza la vista de la estructura (consulte navigating).

### La API de &kile;

El objeto (variable) global `kile` se utiliza para gestionar las interacciones de nivel superior con el mundo exterior, los mensajes de entrada y los diálogos de las interfaces. Estas llamadas de la API están divididas en subobjetos para estructurar esta parte de la API de ejecución de scripts. Conceptualmente `kile` es similar a una `ventana` en la API de un navegador.

- `kile.alert`: cuadros de mensajes

- `kile.input`: obtener la entrada del usuario

- `kile.wizard`: llamar a uno de los asistentes de &kile;

- `kile.script`: obtener información sobre un script en ejecución

- `kile.file`: operaciones de archivo como leer y escribir.

#### Alerta

    void kile.alert.information(String texto, String titulo);

- Muestra un diálogo de información. Donde `texto` es el mensaje y `caption` es el título del cuadro de diálogo. El título predeterminado es el nombre del script.

    void kile.alert.sorry(String texto, String titulo);

- Muestra un diálogo de disculpa. Donde `texto` es el mensaje y `titulo` es el título del cuadro de mensaje. El título predeterminado el nombre del script.

    void kile.alert.error(String texto, String titulo);

- Muestra un diálogo de error. Donde `texto` es el mensaje y `titulo` es el título del cuadro de mensaje. El título predeterminado es el nombre del script.

    String kile.alert.question(String texto, String titulo);

- Muestra un diálogo de pregunta sencillo. Donde `texto` es el mensaje y `titulo` es el título del cuadro de mensaje. El título predeterminado es el nombre del script. El string devuelto puede ser `yes` (sí) o `no` (no).

    String kile.alert.warning(String text, String caption);

- Muestra un diálogo de advertencia sencillo. Donde `texto` es el mensaje y `titulo` es el título del cuadro de mensaje. El título predeterminado es el nombre del script. El string devuelto puede ser `continue` (continuar) o `cancel` (cancelar).

#### Entrada

    String kile.input.getListboxItem(String titulo, String etiqueta, StringList lista);

- Función que permite al usuario seleccionar un elemento de una lista, que se muestra como un cuadro lista. Donde `titulo` es el texto que se muestra en la barra de título, `etiqueta` es el texto que aparece como la etiqueta de la lista y `lista` es la lista de strings en la que está incluida en la lista.

    String kile.input.getComboboxItem(String titulo, String etiqueta, StringList lista);

- Función que permite al usuario seleccionar un elemento de una lista, que se muestra como una lista despegable. Donde `titulo` es el texto que se muestra en la barra de título, `etiqueta` es el texto que aparece como la etiqueta de la lista y `lista` es la lista de strings en la que está incluida en la lista.

    String kile.input.getText(String titulo, String etiqueta);

- Función que obtiene una cadena de texto del usuario. Donde `titulo` es el texto que se muestra en la barra de título y `etiqueta` es el texto que aparece como la etiqueta de la línea de edición.

    String kile.input.getLatexCommand(String titulo, String etiqueta);

- Función para obtener una orden &latex; del usuario. Esto significa que solo se permiten letras en minúscula y en mayúscula. Donde `titulo` es el texto que se muestra en la barra de titulo y `etiqueta` es el texto que aparece como la etiqueta de la línea de edición.

    int kile.input.getInteger(String titulo, String etiqueta, int min = INT_MIN, int max = INT_MAX);

- Función para obtener un entero del usuario. `titulo` es el texto que se muestra en la barra de título. `etiqueta` es el texto que aparece como la etiqueta del spin box. `min` y `max` son los valores mínimo y máximo permitidos que el usuario puede escoger. Los valores predeterminados son `INT_MIN` y `INT_MAX`.

    int kile.input.getPosInteger(String titulo, String etiqueta, int min = 1, int max = INT_MAX);

- Función para obtener un entero positivo del usuario. `titulo` es el texto que se muestra en la barra de título. `etiqueta` es el texto que aparece como la etiqueta del spin box. `min` y `max` son los valores mínimo y máximo permitidos que el usuario puede escoger. Los valores predeterminados son `1` y `INT_MAX`.

#### Asistente

    void kile.wizard.tabular();

- Llama al Asistente de tabla, que ayuda a escribir un entorno «tabular» (consulte wizard_array).

    void kile.wizard.array();

- Llama al Asistente de matriz, que ayuda a escribir un entorno «array» (consulte wizard_array).

    void kile.wizard.tabbing();

- Llama al Asistente de tabulación, que ayuda a escribir un entorno «tabbing» (consulte wizard_array).

    void kile.wizard.floatEnvironment();

- Llama al Asistente de flotantes, que ayuda a insertar elementos flotantes (consulte wizard_float).

    void kile.wizard.mathEnvironment();

- Llama al Asistente de matemática, que ayuda a insertar entornos matemáticos (consulte wizard_math).

    void kile.wizard.postscript();

- Llama al Asistente de herramientas de Postscript, que puede ayudar a manipular o reorganizar documentos Postscript (consulte wizard_postscript).

#### Script

    String kile.script.name();

- Devuelve el nombre base de un script en ejecución (sin la ruta ni la extensión).

    String kile.script.caption();

- Devuelve un string, que se puede utilizar como título de los diálogos de alerta. Su apariencia es similar a `Script: nombrescript.js`.

#### Archivo

    Object kile.file.read(String nombreDeArchivo);

- Lee el contenido de un archivo de texto. Se utiliza de la siguiente forma

  Ejemplo: `var res = kile.file.read(«ruta/al/archivo.txt»);`

  El valor de retorno `res` es un objeto (mejor dicho: un mapa) con tres propiedades:

  - status: Da el código de estado de la operación, que puede ser 0 (sin error), 1 (fallo de acceso) o 2 (acceso denegado). Por tanto, si no ocurre ningún error, el valor de `res.status` o `res["status"]` será 0.

  - result: Contiene el texto del archivo indicado.

  - message: Contiene un mensaje de error, si ha ocurrido un error.

    Object kile.file.read();

- Similar a `read(nombreDeArchivo)`, pero no se indica ningún nombre de archivo. Aparecerá un diálogo para seleccionar el archivo a leer.

    Object kile.file.write(String nombreDeArchivo, String texto);

- Escribe el texto indicado en un archivo. Se utiliza de la siguiente forma

  Ejemplo: `var res = kile.file.write(«ruta/al/archivo.txt»,«Algún texto…»);`

  El valor retornado `res` es un objeto (mejor dicho: un mapa) con dos propiedades: `status` y `message` (consulte `read()` para más información).

    Object kile.file.write(String texto);

- Similar a `write(nombreDeArchivo,texto)`, pero no se indica ningún nombre de archivo. Aparecerá un diálogo para seleccionar un archivo.

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

- Crea un diálogo de archivo modal y devuelve el nombre del archivo seleccionado o un string vacío si no se selecciona ninguno. Tenga en cuenta que con este método el usuario debe seleccionar un archivo existente.

  Parámetros:

  - dirInicio: Directorio de inicio del diálogo de apertura.

  - filtro: Un englobador de la interfaz de ordenes o un filtro de tipos MIME que especifica que archivos mostrar. Remítase a la documentación de KFileDialog para más información sobre este parámetro.

  Ambos parámetros son opcionales. Si se omite `filtro`, se mostrarán todos los archivos. Si además se omite `dirInicio`, el diálogo tomará el directorio del documento actual como punto de inicio.

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

- Crea un diálogo de archivo modal y devuelve el nombre del archivo seleccionado o un string vacío si no se selecciona ninguno. Tenga en cuenta que con este método el usuario no debe seleccionar un archivo existente. Consulte `getOpenFileName()` para una explicación de los parámetros.

## Ejemplos

Algunos ejemplos pueden ayudarle a comprender como utilizar el API de ejecución de scripts. Estos ejemplos y algunos más se encuentran en el directorio de scripts de &kile;: `KILE_APP_DIR/scripts/`. Cada script contiene una breve descripción.

### Ejemplo 1: reemplazar el nombre del entorno

Reemplaza el entorno &latex; circundante con otro, donde la posición relativa del cursor no se cambiará. Por ejemplo, se puede cambiar `\begin{abc}…\end{abc}` por `\begin{xyz}…\end{xyz}`.

    var range = document.environmentRange(false);
    if ( range.isValid() ) {
            var envname = kile.input.getLatexCommand("Enter Environment","New environment name:");
            if ( envname != '' ) {
                    replaceEnvCommand(envname,range);
            }
    }
    else {
            kile.alert.sorry("No surrounding LaTeX environment found.");
    }

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

### Ejemplo 2: reemplazar una orden &latex; de tipo de letra.

Reemplaza una orden de tipo de letra &latex; circundante con otra orden de tipo de letra, cuando el cursor está ubicado dentro de un grupo de texto. La posición relativa del cursor no será modificada. Por ejemplo, se puede cambiar `\textbf{abc}` por `\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 surrounding TeX group found.");
    }

    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",
                                                        "Choose font command:",buildCmdList(cmd));
                            if ( newcommand != "" ) {
                                    document.replaceText(cmdRange,newcommand);
                                    c.column = c.column - (cmd.length - newcommand.length);
                            }
                    }
    /                view.setCursorPosition(c);
            }
            else {
                    kile.alert.sorry("No surrounding font command found.");
            }
            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;
    }

### Ejemplo 3: Rodear texto seleccionado

Rodea el texto seleccionado con una orden TeX, donde la posición relativa del cursor no será modificada. Por ejemplo, `abc` se puede cambiar por `\ordentex{abc}`

    var range = view.selectionRange();

    if ( range.isValid() ) {
            var cmd = kile.input.getLatexCommand("Choose","Choose surrounding LaTeX command:");
            if ( cmd != "" ) {
                    surroundTexCommand("\\"+cmd,range);
            }
    }
    else {
            kile.alert.sorry("No selection found.");
    }

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