# Programação

## Programação no &kile;

A funcionalidade de programação do &kile; permite a execução de código em ECMAScript, vulgarmente conhecido como &javascript;. Irá encontrar um enorme conjunto de tutoriais, que fornecem informações acerca dos objectos (variáveis), funções e propriedades suportadas pelo &javascript;.

O suporte de programação poderá ser activado na janela de configuração do &kile;: Configuração Configurar o Kile... Kile Programação. Activar ou desactivar o suporte de programação Activar ou desactivar o suporte de programação

Se a programação estiver activa, ficará visível um painel de programação adicional na barra lateral, onde poderá gerir os programas: Painel de programação na barra lateral Painel de programação na barra lateral

Este elemento contém seis ícones, que oferecem diferentes tarefas:

- Executar o programa seleccionado.

- Criar um novo programa.

- Abrir o programa seleccionado no editor.

- Configurar uma sequência de teclas para o programa seleccionado.

- Remover uma sequência de teclas atribuída.

- Actualizar a lista de programas disponíveis, os quais poderá encontrar em `$`KDEDIR`/share/apps/kile/scripts/`.

## Executar um Programa

Poderá executar um programa de três formas diferentes:

1. Seleccione o programa desejado e carregue no botão Executar do lado esquerdo do item de gestão dos programas.

   Programação: botão de execução
   Programação: botão de execução

2. Usar um atalho de teclado.

   Programação: atalho de teclado
   Programação: atalho de teclado

   Poderá atribuir um atalho de teclado a um programa, usando o botão Configurar no item de gestão dos programas.

   Programação: janela de configuração das sequências
   Programação: janela de configuração das sequências

3. Usar uma sequência de teclas do editor. O programa será executado se indicar a sequência de teclas atribuída no editor.

   Programação: editor de sequências de teclas
   Programação: editor de sequências de teclas

   Este método poderá ser extendido a um tipo de completação relativamente sofisticado. Iremos assumir que acabou de escrever um programa que introduz simplesmente o comando de &latex; `\textbf{}` no documento actual.

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

   Se agora escrever a sequência atribuída `bfx` no seu documento de texto, esta sequência será removida e o programa será executada. Irá introduzir `\textbf{}` e o cursor ficará colocado entre as chavetas.

   Programação: introduzir uma sequência de teclas no editor
   Programação: introduzir uma sequência de teclas no editor

   É realmente um método confortável e poderoso de completar código.

## Referência da API

A API de programação aqui apresentada está disponível em todos os programas. Antes de o conteúdo de um programa ser carregado, o &kile; adiciona primeiro vários protótipos e funções ao contexto de programação. Esta API de conveniência contém protótipos como por exemplo cursores e intervalos de texto, estando localizada na pasta `KILE_APP_DIR/script-plugins/`.

Os programas do &kile; são ligeiramente diferentes dos programas do &kate;, que usam outro desenho, na medida em que também poderão ser iniciados a partir da linha de comandos. Contudo, todas as funções da API de programação do &kate; estão também disponíveis na API de programação do &kile;, pelo que a migração do código de &javascript; do &kate; para o &kile; deverá ser bastante simples. Contudo, dado que o &kile; é um editor de texto bastante pleno em funcionalidades de &latex;, a sua própria API de programação oferece muito mais possibilidades que a do &kate;.

Comentário: A descrição das chamadas da API que estão disponíveis na programação do &kate; foram retiradas da documentação do &kate;.

### Funções Globais

Esta secção apresenta as funções globais.

    void debug(String texto);

  Imprime o `texto` para o `stdout` na consola. O texto impresso é colorido para o distinguir de outros dados de depuração.

### O Protótipo do Cursor

Dado que o &kile; é um editor de texto, toda a API de programação baseia-se em cursores e intervalos sempre que possível. Um Cursor é um simples tuplo `(linha, coluna)` que representa uma posição de texto no documento.

    Cursor();

  Construtor: Devolve um Cursor na posição `(0,0)`.

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

    Cursor(int linha, int coluna);

  Construtor: Devolve um Cursor na posição (linha,coluna).

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

    Cursor(Cursor outro);

  Construtor por cópia: Devolve uma cópia do cursor `outro`.

  Exemplo: `var copia = new Cursor(outro);`

    Cursor Cursor.clone();

  Devolve uma cópia do cursor.

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

    bool Cursor.isValid();

  Verifica se o cursor é válido. O cursor é inválido no caso em que a linha e/ou coluna sejam iguais a `-1`.

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

    Cursor Cursor.invalid();

  Devolve um novo cursor inválido que se localiza em `(-1,-1)`.

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

    int Cursor.compareTo(Cursor outro);

  Compara este cursor com o cursor `outro`. Devolve

  - `-1`, se este cursor se localizar antes do cursor `outro`,

  - `0`, se ambos os cursores forem iguais e

  - `+1`, se este cursor se localizar depois do cursor `outro`.

    bool Cursor.equals(Cursor outro);

  Devolve `true` (verdadeiro), se este cursor e o cursor `outro` forem iguais, caso contrário devolve `false` (falso).

    String Cursor.toString();

  Devolve o cursor como uma sequência de texto no formato `Cursor(linha,coluna)`.

### O Protótipo do Intervalo

Dado que o &kile; é um editor de texto, toda a API de programação baseia-se nos conceitos de cursores e intervalos, sempre que possível. Dado que o Cursor é um simples tuplo `(linha, coluna)` que representa uma posição de texto no documento, um Range abrange o texto desde uma dada posição inicial até uma posição final.

    Range();

  Construtor: Se invocar `new Range()`, irá obter um intervalo Range de `(0,0) - (0,0)`.

    Range(Cursor inicio, Cursor fim);

  Construtor: A invocação de `new Range(início, fim)` devolve o intervalo do cursor `início` até ao cursor `fim`.

    Range(int linhaInicial, int colunaInicial, int linhaFinal, int colunaFinal);

  Construtor: A invocação de `new Range(linhaInicio,colunaInicio,linhaFim, colunaFim)` devolve o intervalo de (`linhaInicio`, `colunaInicio`) até (`linhaFim`, `colunaFim`).

    Range(Range outro);

  Construtor por cópia: Devolve uma cópia do intervalo Range `outro`.

    Range Range.clone();

  Devolve uma cópia do intervalo.

  Exemplo: `var clone = intervalo.clone();`

    bool Range.isValid();

  Devolve `true` (verdadeiro), se tanto o cursor de início como o de fim forem válidos, caso contrário devolve `false` (falso).

  Exemplo: `var valido = intervalo.isValid();`

    bool Range.invalid();

  Devolve o intervalo Range de (-1,-1) até (-1,-1).

    bool Range.contains(Cursor cursor);

  Devolve `true` (verdadeiro) se este intervalo contiver a posição do cursor, caso contrário devolve `false`.

    bool Range.contains(Range outro);

  Devolve `true` (verdadeiro) se este intervalo tiver dentro dele o intervalo `outro`, caso contrário `false` (falso).

    bool Range.containsColumn(int coluna);

  Devolve `true` (verdadeiro), se a `coluna` está no intervalo semi-aberto `[início.coluna, fim.coluna)`, caso contrário devolve `false` (falso).

    bool Range.containsLine(int linha);

  Devolve `true` (verdadeiro), se a `linha` está no intervalo semi-aberto `[início.linha, fim.linha)`, caso contrário devolve `false` (falso).

    bool Range.overlaps(Range outro);

  Devolve `true` (verdadeiro) se este intervalo e o `outro` partilharem uma região em comum, caso contrário devolve `false` (falso).

    bool Range.overlapsLine(int linha);

  Devolve `true`, se a `linha` estiver no intervalo `[início.linha, fim.linha]`, caso contrário `false`.

    bool Range.overlapsColumn(int coluna);

  Devolve `true`, se a `coluna` estiver no intervalo `[início.coluna, fim.coluna]`, caso contrário `false`.

    bool Range.equals(Range outro);

  Devolve `true` se este intervalo e o `outro` forem iguais, caso contrário devolve `false`.

    String Range.toString();

  Devolve o intervalo como um texto no formato `Range(Cursor(linha,coluna) - Cursor(linha,coluna))`.

### A API do View

Sempre que um programa for executado, existe uma variável global `view` que representa a janela de edição activa de momento. Todas as funções do `view` funcionam com posições do cursor ou com o texto seleccionado. Segue-se uma lista com todas as funções disponíveis do `view`.

    void view.backspace();

  Efectua, de forma programada, o equivalente a carregar na tecla Backspace.

    Cursor view.cursorPosition();

  Devolve a posição actual do cursor na janela.

    void view.setCursorPosition(int linha, int coluna);
    void view.setCursorPosition(Cursor cursor);

  Muda a posição actual do cursor para `linha`, `coluna` ou para o `cursor` indicado.

    void view.cursorLeft();

  Move o cursor uma posição para trás no texto.

    void view.cursorRight();

  Move o cursor uma posição para a frente no texto.

    void view.cursorUp();

  Move o cursor uma linha para cima no texto.

    void view.cursorDown();

  Move o cursor uma linha para baixo no texto.

    int view.cursorLine();

  Devolve a linha em que o cursor se encontra nest momento.

    int view.cursorColumn();

  Devolve a coluna em que o cursor se encontra nest momento.

    void view.setCursorLine(int linha);

  Muda a linha do cursor para a `linha` indicada.

    void view.setCursorColumn(int coluna);

  Muda a coluna do cursor para a `coluna` indicada.

    Cursor view.virtualCursorPosition();

  Obtém a posição actual virtual do cursor. Virtual significa que as tabulações contam como vários caracteres, de acordo com a configuração do utilizador (p.ex., um TAB corresponde a 8 espaços). A posição virtual do cursor oferece acesso aos valores visíveis para o utilizador da posição actual do cursor.

    bool view.hasSelection();

  Devolve `true` (verdadeiro) se a janela contiver algum texto seleccionado, caso contrário devolve `false`.

    String view.selectedText();

  Devolve o texto seleccionado. Se não estiver nenhum texto seleccionado, o texto devolvido vem vazio.

    Range view.selectionRange();

  Devolve o intervalo de texto seleccionado. O intervalo devolvido é inválido, caso não esteja seleccionado nenhum texto.

    void view.setSelection(Range intervalo);

  Muda o texto seleccionado para o `intervalo` indicado.

    void view.selectAll();

  Selecciona o texto por inteiro no documento.

    void view.clearSelection();

  Limpa a selecção de texto actual, sem remover o texto.

    void view.removeSelectedText();

  Remove o texto seleccionado. Se a janela não tiver nenhuma selecção feita, isto não faz nada.

    void view.selectLine();

  Selecciona o texto na linha actual.

    void view.selectLine(int linha);

  Selecciona o texto na `linha` indicada.

    void view.selectLines(int de, int ate);

  Selecciona o texto inteiro desde a linha `de` até à linha `ate`.

    void view.selectWord();

  Selecciona a palavra actual. Se não tiver sido encontrada nenhuma palavra na posição actual do cursor, não é feito nada.

    void view.selectLatexCommand();

  Selecciona o comando de &latex; actual. Se não for encontrado nenhum comando na posição actual do cursor, não é feito nada.

    void view.selectEnvironment(bool dentro = false);

  Selecciona o texto inteiro do ambiente de &latex; actual. Se o parâmetro `dentro` for `false`, será seleccionado o texto do ambiente por completo, incluindo as marcas de &latex; envolventes `\begin{...}...\end{...}`, caso contrário só será seleccionado o texto dentro dessas marcas. Se não for indicado nenhum parâmetro, o valor de `dentro` será igual a `false`.

    void view.selectTexgroup(bool dentro = true);

  Selecciona o texto inteiro do grupo de &latex; actual. Se o parâmetro `dentro` for `true`, só será seleccionado o texto do grupo sem as marcas envolventes. Se não for indicado nenhum parâmetro, o valor de `dentro` será igual a `true`.

    void view.selectMathgroup();

  Selecciona o texto do grupo matemático actual.

    void view.selectParagraph(bool linhasCompletas = true);

  Selecciona o texto inteiro do parágrafo de &latex; actual. Se o parâmetro `linhasCompletas` for `true`, serão incluídas a primeira e última linhas do parágrafo na selecção por inteiro (incluindo o carácter de fim-de-linha; caso contrário, a selecção só irá conter caracteres não-brancos.

### A API do Document

Sempre que um programa for executado, existe uma variável global `document` que representa o documento activo de momento. Segue-se uma lista com todas as funções disponíveis do `document`.

    void document.insertText(String texto);

  Insere o `texto` na posição actual do cursor.

    void document.insertText(int linha, int coluna, String texto);
    void document.insertText(Cursor cursor, String texto);

  Insere o `texto` na posição do cursor indicada.

    bool document.removeText(int daLinha, int dacoluna, int ateLinha, int ateColuna);
    bool document.removeText(Cursor de, Cursor ate);
    bool document.removeText(Range intervalo);

  Remove o texto no intervalo indicado. Devolve `true` (verdadeiro), em caso de sucesso, ou `false` (falso), se o documento estiver no modo apenas para leitura.

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

  Substitui o texto do intervalo indicado pelo texto passado como parâmetro.

    int document.lines();

  Devolve o número de linhas do documento.

    int document.length();

  Devolve o número de caracteres do documento.

    Range document.documentRange();

  Devolve um intervalo que engloba todo o documento.

    Cursor document.documentEnd();

  Devolve a posição de cursor do fim do documento.

    String document.text();

  Devolve todo o conteúdo do documento numa única sequência de texto. As mudanças de linhas são marcadas com o carácter de mudança de linha `\n`.

    String document.text(int daLinha, int daColuna, int ateLinha, int ateColuna);
    String document.text(Cursor de, Cursor ate);
    String document.text(Range intervalo);

  Devolve o texto no intervalo indicado. Recomenda-se que use a versão baseada nos cursores e nos intervalos, de modo a ter uma melhor visibilidade do código-fonte.

    bool document.setText(String texto);

  Altera o texto do documento por inteiro.

    bool document.clear();

  Limpa o texto no documento por inteiro.

    String document.line();

  Devolve a linha do texto actual no formato de texto.

    String document.line(int linha);

  Devolve a linha de texto indicada como uma sequência de texto. O texto devolvido fica em branco, caso a linha pedida esteja fora do intervalo.

    int document.lineLength();

  Devolve o comprimento da linha actual.

    int document.lineLength(int linha);

  Devolve o comprimento da `linha`.

    bool document.insertLine(String s);

  Insere o texto na linha actual. Devolve `true` em caso de sucesso, ou `false`, caso o documento esteja no modo apenas para leitura ou se a linha não estiver no intervalo do documento.

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

  Insere o texto na linha indicada. Devolve `true` (verdadeiro), em caso de sucesso, ou `false` (falso), caso o documento esteja apenas para leitura ou se a linha não estiver no intervalo do documento.

    bool document.removeLine();

  Remove a linha de texto actual. Devolve `true` em caso de sucesso ou `false` se o documento estiver no modo apenas para leitura.

    bool document.removeLine(int linha);

  Remove a linha de texto indicada. Devolve `true` (verdadeiro), em caso de sucesso, ou `false` (falso), caso o documento esteja no modo apenas para leitura ou se a linha não estiver no intervalo do documento.

    bool document.replaceLine(String texto);

  Substitui o texto da linha actual pelo texto indicado.

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

  Substitui o texto da linha indicada pelo texto passado como parâmetro.

    bool document.truncateLine();

  Corta a linha actual na coluna ou posição do cursor indicada. Devolve `true` em caso de sucesso ou `false` se a linha indicada não fizer parte do intervalo do documento.

    bool document.truncate(int linha, int coluna);
    bool document.truncate(Cursor cursor);

  Trunca a linha indicada, na coluna ou posição do cursor indicadas. Devolve `true` (verdadeiro) em caso de sucesso ou `false` (falso) se a linha não estiver dentro do intervalo do documento.

    String document.word();

  Devolve a palavra na posição actual do cursor. Se não for encontrada nenhuma palavra nesta posição, o texto devolvido vem vazio.

    String document.wordAt(int linha, int coluna);
    String document.wordAt(Cursor cursor);

  Devolve a palavra na posição actual do cursor. Se não for encontrada nenhuma palavra na posição do cursor, o texto devolvido será vazio.

    Range document.wordRange();

  Devolve o intervalo da palavra na posição actual do cursor. Se não for encontrada nenhuma palavra, será devolvido `Range.invalid()`, valor que poderá ser testado com o `Range.isValid()`.

    String document.latexCommand();

  Devolve o comando de &latex; na posição actual do cursor. Se não for encontrado nenhum comando nesta posição do cursor, o texto devolvido estará em branco.

    String document.latexCommandAt(int linha, int coluna);
    String document.latexCommandAt(Cursor cursor);

  Devolve o comando de &latex; na posição indicada pelo cursor. Se não for encontrado nenhum comando nesta posição, o texto devolvido estará vazio.

    Range document.latexCommandRange();

  Devolve o intervalo do comando de &latex; na posição actual do cursor. Se não for encontrado nenhum comando de &latex;, é devolvido `Range.invalid()`, o que poderá ser testado com o `Range.isValid()`.

    String document.charAt(int linha, int coluna);
    String document.charAt(Cursor cursor);

  Devolve o carácter na posição do cursor indicada.

    String document.firstChar(int linha);

  Devolve o primeiro carácter na `linha` que não seja um espaço em branco. O primeiro carácter encontra-se na coluna 0. Se a linha estiver em branco ou se só tiver espaços em branco, o texto devolvido está vazio.

    String document.lastChar(int linha);

  Devolve o último carácter na `linha` que não seja um espaço em branco. Se a linha estiver em branco ou se só tiver espaços em branco, o texto devolvido está vazio.

    bool document.isSpace(int linha, int coluna);
    bool document.isSpace(Cursor cursor);

  Devolve `true` (verdadeiro), se o carácter na posição indicada do cursor for um espaço em branco, caso contrário devolve `false` (falso).

    void document.insertBullet();

  Insere um ponto de tópico do &kile;. Lembre-se que poderá ir facilmente para o ponto anterior ou seguinte. Isto irá também realçar este ponto, pelo que será apagado automaticamente, sempre que introduzir a sua primeira letra.

    void document.nextBullet();

  Salta para o próximo ponto do texto, se existir.

    void document.previousBullet();

  Salta para o ponto anterior no texto, se existir.

    bool document.hasEnvironment();

  Devolve `true` se for encontrado um ambiente de &latex; envolvente, caso contrário devolve `false`.

    String document.environment(bool dentro = false);

  Selecciona o texto inteiro do ambiente de &latex; envolvente. Se o parâmetro `dentro` for `false`, será seleccionado o texto do ambiente por completo, incluindo as marcas de &latex; envolventes `\begin{...}...\end{...}`, caso contrário só será seleccionado o texto dentro dessas marcas. Se não for indicado nenhum parâmetro, o valor de `dentro` será igual a `false`. Se não for encontrado nenhum ambiente, é devolvido um texto vazio.

    Range document.environmentRange(bool dentro = false);

  Selecciona o texto inteiro do ambiente de &latex; envolvente. Se o parâmetro `dentro` for `false`, será seleccionado o texto do ambiente por completo, incluindo as marcas de &latex; envolventes `\begin{...}...\end{...}`, caso contrário só será seleccionado o texto dentro dessas marcas. Se não for indicado nenhum parâmetro, o valor de `dentro` será igual a `false`. Se não for encontrado nenhum ambiente, é devolvido um texto vazio.

    String document.environmentName();

  Devolve o nome do ambiente de &latex; envolvente, ou então um texto vazio.

    void document.removeEnvironment(bool dentro = false);

  Selecciona o texto inteiro do ambiente de &latex; actual. Se o parâmetro `dentro` for `false`, será seleccionado o texto do ambiente por completo, incluindo as marcas de &latex; envolventes `\begin{...}...\end{...}`, caso contrário só será seleccionado o texto dentro dessas marcas. Se não for indicado nenhum parâmetro, o valor de `dentro` será igual a `false`.

    void document.closeEnvironment();

  Insere uma marca de fecho do ambiente, caso esteja um ambiente de &latex; aberto na posição actual do cursor.

    void document.closeAllEnvironments();

  Insere marcas de fecho dos ambientes para todos os ambientes de &latex; abertos que tenham sido encontrados na posição actual do cursor.

    bool document.hasTexgroup();

  Devolve `true` se tiver sido encontrado um grupo de &latex; envolvente na posição actual do cursor, caso contrário devolve `false`.

    String document.texgroup(bool dentro = true);

  Selecciona o texto inteiro do ambiente de &latex; envolvente. Se o parâmetro `dentro` for `false`, será seleccionado o texto do ambiente por completo, incluindo as marcas de &latex; envolventes `\begin{...}...\end{...}`, caso contrário só será seleccionado o texto dentro dessas marcas. Se não for indicado nenhum parâmetro, o valor de `dentro` será igual a `false`. Se não for encontrado nenhum ambiente, é devolvido um texto vazio.

    Range document.texgroupRange(bool dentro = true);

  Selecciona o intervalo do grupo de &latex; envolvente. Se o parâmetro `dentro` for `false`, será devolvido o intervalo que inclui as chavetas `{...}`, caso contrário estas serão excluídas. Se não for indicado nenhum parâmetro, o valor de `dentro` será igual a `false`. Se não for encontrado nenhum grupo é devolvido o `Range.invalid()`, que poderá ser testado com o `Range.isValid()`.

    void document.removeTexgroup(bool dentro = true);

  Selecciona o texto inteiro do ambiente de &latex; actual. Se o parâmetro `dentro` for `false`, será seleccionado o texto do ambiente por completo, incluindo as marcas de &latex; envolventes `\begin{...}...\end{...}`, caso contrário só será seleccionado o texto dentro dessas marcas. Se não for indicado nenhum parâmetro, o valor de `dentro` será igual a `false`.

    bool document.hasMathgroup();

  Devolve `true` se for encontrado um grupo matemático de &latex; na posição actual do cursor, caso contrário `false`.

    String document.mathgroup();

  Devolve o texto do grupo matemático de &latex; envolvente. O texto devolvido será vazio se não for encontrado nenhum grupo matemático de &latex; na posição actual do cursor.

    Range document.mathgroupRange();

  Devolve o intervalo do grupo matemático de &latex; envolvente. Se não for encontrado nenhum grupo matemático, é devolvido o valor `Range.invalid()`, que poderá ser testado com o `Range.isValid()`.

    void document.removeMathgroup();

  Remove o texto do grupo matemático de &latex; envolvente.

    String document.paragraph();

  Devolve o texto do parágrafo de &latex; actual.

    Range document.paragraphRange();

  Devolve o intervalo do parágrafo de &latex; envolvente.

    void document.removeParagraph();

  Remove o texto do parágrafo de &latex; actual.

    bool document.matchesAt(int linha, int coluna, String texto);
    bool document.matchesAt(Cursor cursor, String texto);

  Devolve `true` se o `texto` indicado corresponder à posição actual do cursor, caso contrário devolve `false`.

    bool document.startsWith(int linha, String padrao, bool ignorarEspacos = true);

  Devolve `true`, se a linha começar com o `padrao`, caso contrário devolve `false`. O argumento `ignorarEspacos` controla se são ignorados os espaços iniciais.

    bool document.endsWith(int linha, String padrao, bool ignorarEspacos = true);

  Devolve `true`, se a linha terminar com o `padrao`, caso contrário devolve `false`. O argumento `ignorarEspacos` controla se são ignorados os espaços iniciais.

    int document.firstColumn(int linha);

  Devolve a primeira coluna sem espaços em branco na `linha` indicada. Se só existirem espaços em branco nessa linha, o valor devolvido é `-1`.

    int document.lastColumn(int linha);

  Devolve a última coluna sem espaços em branco na `linha` indicada. Se só existirem espaços em branco nessa linha, o valor devolvido é `-1`.

    int document.prevNonSpaceColumn(int linha, int coluna);
    int document.prevNonSpaceColumn(Cursor cursor);

  Devolve a coluna com caracteres não-brancos que começa na posição de cursor indicada e pesquisa para trás.

    int document.nextNonSpaceColumn(int linha, int coluna);
    int document.nextNonSpaceColumn(Cursor cursor);

  Devolve a coluna com caracteres não-brancos que começa na posição de cursor indicada e pesquisa para a frente.

    int document.prevNonEmptyLine(int linha);

  Devolve a primeira linha não-vazia que contém caracteres não-nulos, pesquisando depois para trás.

    int document.nextNonEmptyLine(int linha);

  Devolve a primeira linha não-vazia que contém caracteres não-nulos, pesquisando depois para a frente.

    void document.gotoBeginEnv();

  Vai para o início de um ambiente de &latex; envolvente.

    void document.gotoEndEnv();

  Vai para o fim de um ambiente de &latex; envolvente.

    void document.gotoBeginTexgroup();

  Vai para o início de um grupo de &latex; envolvente.

    void document.gotoEndTexgroup();

  Vai para o fim de um grupo de &latex; envolvente.

    void document.gotoNextParagraph();

  Vai para o parágrafo de &latex; seguinte.

    void document.gotoPrevParagraph();

  Vai para o parágrafo de &latex; anterior.

    void document.gotoNextSectioning();

  Vai para a secção de &latex; seguinte.

    void document.gotoPrevSectioning();

  Vai para a secção de &latex; anterior.

    void document.gotoLine(int linha);

  Vai para a `linha` indicada.

    void document.insertChapter();

  Introduz um comando `\chapter` (ver também `document.insertSection()`).

    void document.insertSection();

  Insere um comando `\section`. Como na escolha da opção LaTeX Secções section, irá aparecer uma janela onde poderá escolher o título e uma legenda opcional para este comando. Janela: comando de inserção de um capítulo Janela: comando de inserção de um capítulo

    void document.insertSubsection();

  Insere um comando `\subsection` (ver também o `document.insertSection()`).

    void document.insertSubsubsection();

  Insere um comando `\subsubsection` (ver também o `document.insertSection()`).

    void document.insertParagraph();

  Insere um comando `\paragraph` (ver também o `document.insertSection()`).

    void document.insertSubparagraph();

  Insere um comando `\subparagraph` (ver também o `document.insertSection()`).

    void document.insertLabel();

  Insere um comando `\label`.

    void document.insertReference();

  Insere um comando `\ref`. Como na escolha da opção &latex;Referências section, irá aparecer uma janela onde poderá escolher uma das legendas já definidas na lista. Janela: comando de inserção de referência Janela: comando de inserção de referência

    void document.insertPageref();

  Insere um comando `\pageref` (ver também o `document.insertReference()`).

    void document.insertCitation();

  Insere um comando `\cite`.

    void document.insertIndex();

  Insere um comando `\index`.

    void document.insertFootnote();

  Insere um comando `\footnote`.

    void document.comment();

  Insere marcadores de comentários para tornar o texto seleccionado ou a linha actual um comentário.

    void document.uncomment();

  Remove os marcadores de comentários da selecção ou da linha actual.

    void document.uppercase();

  Coloca o texto seleccionado ou a letra a seguir ao cursor em maiúsculas.

    void document.lowercase();

  Coloca o texto seleccionado ou a letra a seguir ao cursor em minúsculas.

    void document.capitalize();

  Capitaliza (coloca a primeira letra em maiúsculas e as restantes em minúsculas) o texto seleccionado ou a palavra actual.

    void document.joinLines();

  Junta as linhas da selecção actual. Duas linhas consecutivas são sempre separadas por um único espaço.

    void document.insertIntelligentNewline();

  Insere uma mudança de linha inteligente (ver em ).

    void document.insertIntelligentTabulator();

  Insere uma tabulação inteligente (ver em ).

    void document.editBegin();

  Inicia um grupo de edição para agrupar operações a desfazer/refazer. Certifique-se que invoca sempre o `editEnd()` tantas vezes como invoca o `editBegin()`. A invocação do `editBegin()` usa um contador de referências interno, i.e., esta chamada pode ser encadeada.

    void document.editEnd();

  Termina um grupo de edição. A última invocação do `editEnd()` (i.e., a correspondente à primeira chamada do `editBegin()`) termina o passo de edição.

    StringList document.labelList();

  Devolve todas as legendas como um `StringList`, que poderá ser usado no &javascript; como uma lista de objectos.

    StringList document.bibitemList();

  Devolve todos os itens bibliográficos como um `StringList`, que poderá ser usada no &javascript; como uma lista de objectos.

    void document.refreshStructure();

  Actualiza a área da estrutura (ver em ).

### A API do &kile;

A variável global `kile` é usada para lidar com as interacções do nível de topo e o mundo exterior, a introdução de mensagens e de janelas. Estas chamadas da API estão divididas em sub-objectos, por forma a estruturar esta parte da API de programação. Conceptualmente, o `kile` é semelhante ao objecto `window` de um navegador Web.

- `kile.alert`: janelas de mensagens

- `kile.input`: obter dados do utilizador

- `kile.wizard`: invoca um dos assistentes do &kile;

- `kile.script`: obter informações sobre um programa em execução

- `kile.file`: operações de ficheiros, como a leitura ou escrita.

#### Alerta

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

  Mostra uma janela de informações. O `text` é a mensagem propriamente dita e o `titulo` é o título da janela da mensagem. O título por omissão corresponde ao nome do programa.

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

  Mostra uma janela de pedido de desculpa. O `text` é a mensagem propriamente dita e o `titulo` é o título da janela da mensagem. O título por omissão corresponde ao nome do programa.

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

  Mostra uma janela de erros. O `text` é a mensagem propriamente dita e o `titulo` é o título da janela da mensagem. O título por omissão corresponde ao nome do programa.

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

  Mostra uma janela de pergunta. O `text` é a mensagem propriamente dita e o `titulo` é o título da janela da mensagem. O título por omissão corresponde ao nome do programa. O texto devolvido corresponde a `yes` (sim) ou `no` (não).

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

  Mostra uma janela de aviso. O `text` é a mensagem propriamente dita e o `titulo` é o título da janela da mensagem. O título por omissão corresponde ao nome do programa. O texto devolvido corresponde a `continue` (continuar) ou `cancel` (cancelar).

#### Entrada

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

  Uma função para permitir ao utilizador seleccionar um item de uma lista que aparecerá no campo respectivo. O `titulo` é o texto que aparece na barra do título, o `legenda` é o texto que aparece como legenda da lista e a `lista` é a lista de textos que é introduzida no campo propriamente dito.

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

  Uma função para permitir ao utilizador seleccionar um item de uma lista que aparecerá como uma lista apenas com um item visível ('combobox'). O `titulo` é o texto que aparece na barra do título, o `legenda` é o texto que aparece como legenda da lista e a `lista` é a lista de textos que é introduzida no campo propriamente dito.

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

  Função para obter uma sequência de texto do utilizador. O `titulo` é o texto que é apresentado na barra de título e a `legenda` é o texto que aparece como legenda do campo de texto.

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

  Função para obter um comando de &latex; do utilizador. Isto significa que só são permitidas letras maiúsculas e minúsculas. O `titulo` é o texto que é apresentado na barra de título e a `legenda` é o texto que aparece como legenda do campo de texto.

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

  Uma função para pedir um número inteiro ao utilizador. O `titulo` é o texto que aparece na barra do título, a `legenda` é o texto que aparece como legenda do campo incremental. O `min` e o `max` são os valores mínimo e máximo permitidos que o utilizador poderá escolher. Os valores por omissão são o `INT_MIN` e `INT_MAX`, respectivamente.

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

  Uma função para pedir um número inteiro positivo ao utilizador. O `titulo` é o texto que aparece na barra do título, a `legenda` é o texto que aparece como legenda do campo incremental. O `min` e o `max` são os valores mínimo e máximo permitidos que o utilizador poderá escolher. Os valores por omissão são o `INT_MIN` e `INT_MAX`, respectivamente.

#### Assistente

    void kile.wizard.tabular();

  Invoca o Assistente de tabelas, que ajuda a criar um ambiente para o efeito (ver em ).

    void kile.wizard.array();

  Invoca o Assistente de listas, que o ajuda a criar um ambiente de listas (ver em ).

    void kile.wizard.tabbing();

  Invoca o Assistente de separadores, que o ajuda a criar um ambiente de separadores (ver em ).

    void kile.wizard.floatEnvironment();

  Invoca o Assistente de flutuantes, que o ajuda a criar um ambiente de elementos flutuantes (ver em ).

    void kile.wizard.mathEnvironment();

  Invoca o Assistente matemático, que o ajuda a criar um ambiente de elementos flutuantes (ver em ).

    void kile.wizard.postscript();

  Invoca o Assistente de ferramentas PostScript, que o ajuda a manipular ou reorganizar documentos em PostScript (ver em ).

#### Programa

    String kile.script.name();

  Devolve o nome de base de um programa em execução (sem pasta nem extensão).

    String kile.script.caption();

  Devolve um texto para poder ser usado como título de janelas de alerta. Parece-se com o `Script: scriptname.js`.

#### Ficheiro

    Object kile.file.read(String ficheiro);

  Lê o conteúdo de um ficheiro de texto. É usado da seguinte forma

  Exemplo: `var res = kile.file.read("local/do/ficheiro.txt");`

  O valor devolvido `res` é um objecto (um dicionário) com três propriedades:

  - status: Devolve o código de estado da operação, que poderá ser 0 (sem erros), 1 (erro no acesso) ou 2 (acesso negado). Por isso, se não ocorrer nenhum erro, o valor de `res.status` ou `res["status"]` será igual a 0.

  - result: Contém o texto do ficheiro indicado.

  - message: Contém uma mensagem de erro, caso tenha ocorrido algum.

    Object kile.file.read();

  Como o `read(ficheiro)`, mas sem indicar qualquer ficheiro. Irá aparecer uma janela que lhe permite seleccionar o ficheiro a ler.

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

  Grava o texto indicado num ficheiro. É usado da seguinte forma

  Exemplo: `var res = kile.file.write("local/do/ficheiro.txt","Algum texto...");`

  O valor devolvido `res` é um objecto (de facto, um mapa) com duas propriedades: `status` e `message` (ver o `read()` pra mais informações).

    Object kile.file.write(String texto);

  Como o `write(ficheiro,texto)`, só que não é indicado nenhum ficheiro. Irá aparecer uma janela para o escolher.

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

  Cria uma janela de ficheiros modal e devolve o ficheiro seleccionado ou um texto vazio se nenhum ficheiro tiver sido seleccionado. Lembre-se que, com este método, o utilizador deverá seleccionar um ficheiro existente.

  Parâmetros:

  - pastaInicial: A pasta onde é iniciada a janela de abertura.

  - filtro: Um padrão de consola ou um filtro de tipos MIME que indica o tipo de ficheiros a mostrar. Veja a documentação do KFileDialog para obter mais informações sobre este parâmetro.

  Ambos os parâmetros são opcionais. Se omitir o `filtro`, serão apresentados todos os ficheiros. Se também a `pastaInicial` for omitida, será usada a pasta do documento actual como ponto de partida.

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

  Cria uma janela de ficheiros modal e devolve o ficheiro seleccionado ou um texto vazio se nenhum ficheiro tiver sido seleccionado. Lembre-se que, com este método, o utilizador não precisa de seleccionar um ficheiro existente. Veja o `getOpenFileName()` para obter uma explicação dos parâmetros.

## Exemplos

Alguns exemplos poderão ajudar a compreender como usar a API de programação. Estes exemplos, bem como outros mais, encontram-se na pasta de programação do &kile;: `KILE_APP_DIR/scripts/`. Cada programa contém uma breve descrição.

### Exemplo 1: substituir o nome do ambiente

Substitui um ambiente de &latex; envolvente por outro, onde a posição relativa do cursor não será alterada. O `\begin{abc}...\end{abc}`, por exemplo, poderá ser alterado para `\begin{xyz}...\end{xyz}`.

    var intervalo = document.environmentRange(false);
    if ( intervalo.isValid() ) {
            var nome = kile.input.getLatexCommand("Indique o Ambiente","Nome do novo ambiente:");
            if ( nome != '' ) {
                    comandoSubstituir(nome,intervalo);
            }
    }
    else {
            kile.alert.sorry("Não foi encontrado nenhum ambiente de LaTeX envolvente.");
    }

    function comandoSubstituir(novoAmbiente,r)
    {
            var c = view.cursorPosition();

            var nome = document.environmentName();

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

                    document.editBegin();
                    document.replaceText(fim,"\\end{"+novoAmbiente+"}");
                    document.replaceText(inicio,"\\begin{"+novoAmbiente+"}");
                    document.editEnd();
            }
    }

### Exemplo 2: substituir um comando de tipo de letra do &latex;

Substitui um comando de formatação do &latex; envolvente por outro, sendo o cursor colocado dentro do grupo do TeX. A posição relativa do cursor não será alterada. O `\textbf{abc}`, por exemplo, poderá ser alterado para `\textit{abc}`.

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

    var intervalo = document.texgroupRange(false);
    if ( intervalo.isValid() ) {
            comandoSubstituirTexto(intervalo);
    }
    else {
            kile.alert.sorry("Não foi encontrado nenhum grupo de TeX envolvente.");
    }

    function comandoSubstituirTexto(i)
    {
            var c = view.cursorPosition();

            document.editBegin();
            view.setCursorPosition(i.start);
            var cmd = document.latexCommand();
            var indice = fontCommands.indexOf(cmd);
            if ( indce
    >= 0 ) {
                    var intervaloCmd = document.latexCommandRange();
                    if ( intervaloCmd.isValid() ) {
                            var novoComando = kile.input.getListboxItem("Escolher",
                                                        "Escolha o comando:",criarLista(cmd));
                            if ( novoComando != "" ) {
                                    document.replaceText(intervaloCmd,novoComando);
                                    c.column = c.column - (cmd.length - novoComando.length);
                            }
                    }
    /                view.setCursorPosition(c);
            }
            else {
                    kile.alert.sorry("Não foi encontrado nenhum comando de formatação envolvente.");
            }
            document.editEnd();
    }

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

### Exemplo 3: rodear o texto seleccionado

Rodeia o texto seleccionado com um comando de TeX, onde a posição relativa do cursor não será alterada. O `abc` pode ser alterado por exemplo para `\comando{abc}`.

    var intervalo = view.selectionRange();

    if ( intervalo.isValid() ) {
            var cmd = kile.input.getLatexCommand("Escolher","Escolha o comando de LaTeX envolvente::");
            if ( cmd != "" ) {
                    comandoEnvolver("\\"+cmd,intervalo);
            }
    }
    else {
            kile.alert.sorry("Nenhuma selecção efectuada.");
    }

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