# Criação de scripts

## Criação de scripts no &kile;

A funcionalidade de criação de scripts do &kile; permite a execução de código em ECMAScript, popularmente conhecido como &javascript;. Você encontrará um enorme conjunto de tutoriais, que fornecem informações sobre os objetos (variáveis), funções e propriedades suportadas pelo &javascript;.

O suporte a criação de scripts poderá ser ativado na janela de configuração do &kile;: Configurações Configurar o Kile... Kile Criação de scripts. Ativar ou desativar o suporte a criação de scripts Ativar ou desativar o suporte a criação de scripts

Se a criação de scripts estiver ativa, um painel adicional ficará visível na barra lateral, onde seus scripts poderão ser gerenciados: Painel de criação de scripts na barra lateral Painel de criação de scripts na barra lateral

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

- Executar o script selecionado.

- Criar um novo script.

- Abrir o script selecionado no editor.

- Configurar uma sequência de teclas para o script selecionado.

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

- Atualizar a lista de scripts disponíveis, que pode ser encontrada em `$`KDEDIR`/share/apps/kile/scripts/`.

## Executando um script

Você pode executar um script de três formas diferentes:

1. Selecione o script desejado e clique no botão Executar do lado esquerdo do item de gerenciamento de scripts.

   Criação de scripts: botão de execução Criação de scripts: botão de execução

2. Usar um atalho de teclado.

   Criação de scripts: atalho de teclado Criação de scripts: atalho de teclado

   Você poderá atribuir um atalho de teclado a um script, usando o botão Configurar no item de gerenciamento de scripts.

   Criação de scripts: janela de configuração das sequências Criação de scripts: janela de configuração das sequências

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

   Criação de scripts: editor de sequências de teclas Criação de scripts: editor de sequências de teclas

   Este método poderá ser estendido a um tipo de complementação relativamente sofisticado. Iremos assumir que acabou de escrever um script que insere simplesmente o comando de &latex; `\textbf{}` no documento atual.

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

   Se você agora digitar a sequência de teclas atribuída `bfx` no seu documento de texto, esta sequência de teclas será removida e o scripts será executado. Ele irá inserir `\textbf{}` e o cursor será colocado entre as chaves.

   Criação de scripts: inserir uma sequência de teclas no editor Criação de scripts: inserir uma sequência de teclas no editor

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

## Referências da API

A API de criação de scripts apresentada aqui está disponível para todos os scripts. Antes de carregar o conteúdo do script, o &kile; inicialmente adiciona diversos protótipos e funções para o contexto de criação de scripts. Essa conveniente API contém protótipos como cursores e intervalos de texto e está localizada na pasta `KILE_APP_DIR/script-plugins/`.

Os scripts do &kile; diferem levemente dos scripts do &kate;, que usam outro design, uma vez que eles também podem ser iniciados a partir da linha de comando. Mas todas as funções da API de criação de scripts do &kate; estão também disponíveis na do &kile;, assim migrar um código em &javascript; no &kate; para o &kile; deve ser muito simples. Mas uma vez que o &kile; é um editor de &latex; com muitos recursos, sua própria API de criação de scripts oferece muito mais possibilidades do que a do &kate;.

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

### Funções globais

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

    void debug(String texto);

- Imprime o `texto` para o `stdout` no console. O texto impresso é colorido para distingui-lo de outros dados de depuração.

### O Protótipo do Cursor

Uma vez que o &kile; é um editor de texto, toda a API de criação de scripts baseia-se em cursores e intervalos sempre que possível. Um Cursor é um simples dupla `(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 um clone 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

Uma vez que o &kile; é um editor de texto, sempre que possível, toda a API de criação de scripts é baseada em cursores e intervalos. Como um Cursor é uma simples dupla `(linha, coluna)` representando uma posição de texto no documento, um Intervalo estende o texto de uma posição inicial do cursor até uma posição final do cursor.

    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(`linhaInicial`, `colunaInicial`, `linhaFinal`, `colunaFinal`)` devolve um intervalo Range de (`linhaInicial`, `colunaInicial`) até (`linhaFinal`, `colunaFinal`).

    Range(Range outro);

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

    Range Range.clone();

- Devolve um clone 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` (falso).

    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 semiaberto `[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 semiaberto `[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` compartilharem uma região em comum, caso contrário, devolve `false` (falso).

    bool Range.overlapsLine(int linha);

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

    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` (verdadeiro) se este intervalo e o `outro` forem iguais, caso contrário, devolve `false` (falso).

    String Range.toString();

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

### A API do View

Sempre que um programa está sendo executado, existe um objeto global (variável) `view` representando a visão do editor atualmente ativo. Todas as funções do `view` trabalham com posições do cursor ou com o texto selecionado. A seguir é apresentada uma lista de todas as funções disponíveis do `view`.

    void view.backspace();

- Efetua, de forma programada, o equivalente a pressionar a tecla Backspace.

    Cursor view.cursorPosition();

- Devolve a posição atual do cursor na janela.

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

- Muda a posição atual 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 onde o cursor está localizado atualmente.

    int view.cursorColumn();

- Devolve a coluna onde o cursor está localizado atualmente.

    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 atual posição virtual do cursor. Virtual significa que o caractere de tabulação (TAB) vale por múltiplos caracteres, conforme configurado pelo usuário (por exemplo, um TAB equivale a 8 espaços). O posição virtual do cursor fornece acesso aos valores visíveis pelo usuário da posição atual do cursor.

    bool view.hasSelection();

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

    String view.selectedText();

- Devolve o texto selecionado. Se não tiver nenhum texto selecionado, o texto devolvido vem vazio.

    Range view.selectionRange();

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

    void view.setSelection(Range intervalo);

- Muda o texto selecionado para o `intervalo` indicado.

    void view.selectAll();

- Seleciona todo o texto no documento.

    void view.clearSelection();

- Limpa a seleção de texto atual, sem remover o texto.

    void view.removeSelectedText();

- Remove o texto selecionado. Se a janela não tiver nenhuma seleção feita, isto não faz nada.

    void view.selectLine();

- Seleciona o texto na linha atual.

    void view.selectLine(int linha);

- Seleciona o texto na `linha` indicada.

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

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

    void view.selectWord();

- Seleciona a palavra atual. Se nenhuma palavra for encontrada na posição atual do cursor, nada será feito.

    void view.selectLatexCommand();

- Seleciona o comando de &latex; atual. Se nenhum comando for encontrado na posição atual do cursor, nada será feito.

    void view.selectEnvironment(bool inside = false);

- Seleciona todo o texto do ambiente &latex; atual. Se `inside` for `false`, o texto do ambiente incluindo as marcas envolventes do &latex; `\begin{...}...\end{...}` será selecionado, caso contrário, será sem essas marcas. Se nenhum parâmetro for fornecido, `inside` é definido como `false`.

    void view.selectTexgroup(bool dentro = true);

- Seleciona o texto do grupo &latex; atual. Se `inside` for `true`, somente o grupo de texto sem as chaves envolventes será selecionado. Se nenhum parâmetro for fornecido, `inside` é definido como `true`.

    void view.selectMathgroup();

- Seleciona o texto do grupo matemático atual.

    void view.selectParagraph(bool wholeLines = true);

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

### API do Document

Sempre que um script estiver em execução, existe um objeto global (variável) `document` representando o documento ativo atual. A seguir é apresentada uma lista de todas as funções disponíveis para o `document`.

    void document.insertText(String texto);

- Insere o `texto` na posição atual 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 caractere 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 atual 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 atual.

    int document.lineLength(int linha);

- Devolve o comprimento da `linha`.

    bool document.insertLine(String s);

- Insere o texto na linha atual. 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 atual. 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 atual 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();

- Trunca a linha atual 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 atual do cursor. Se nenhum palavra for encontrada 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 atual do cursor. Se nenhuma palavra for encontrada na posição do cursor, o texto devolvido será vazio.

    Range document.wordRange();

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

    String document.latexCommand();

- Devolve o comando de &latex; na posição atual do cursor. Se nenhum comando for encontrado 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 nenhum comando for encontrado nesta posição do cursor, o texto devolvido estará vazio.

    Range document.latexCommandRange();

- Devolve o intervalo do comando de &latex; na posição atual do cursor. Se nenhum comando de &latex; for encontrado, é 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 caractere na posição do cursor indicada.

    String document.firstChar(int linha);

- Devolve o primeiro caractere na `linha` que não seja um espaço em branco. O primeiro caractere encontra-se na coluna 0. Se a linha estiver em branco ou conter apenas espaços, a string devolvida será vazia.

    String document.lastChar(int linha);

- Devolve o último caractere 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 caractere na posição indicada do cursor for um espaço em branco, caso contrário, devolve `false` (falso).

    void document.insertBullet();

- Insere um marcador do &kile;. Lembre-se de que você pode facilmente ir para o próximo marcador ou para o anterior. Isso também realçará este marcador de modo que ele será excluído automaticamente quando inserir sua primeira letra.

    void document.nextBullet();

- Salta para o próximo marcador no texto se houver algum.

    void document.previousBullet();

- Salta para o marcador anterior no texto, se existir.

    bool document.hasEnvironment();

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

    String document.environment(bool inside = false);

- Devolve todo o texto do ambiente envolvente do &latex;. Se `inside` for `false`, o ambiente de texto incluindo as marcas envolventes do &latex; `\begin{...}...\end{...}` será devolvido, caso contrário será sem estas marcas. Se nenhum parâmetro for fornecido, `inside` é definido como `false`. Se nenhum ambiente for encontrado, a string devolvida será vazio.

    Range document.environmentRange(bool dentro = false);

- Devolve o intervalo do ambiente envolvente do &latex;. Se `inside` for `false`, o ambiente de texto incluindo as marcas envolventes do &latex; `\begin{...}...\end{...}` será devolvido, caso contrário, será sem estas marcas. Se nenhum parâmetro for fornecido, `inside` é definido como `false`. Se nenhum ambiente for encontrado, `Range.invalid()` é retornado, o que pode ser testado com `Range.isValid()`.

    String document.environmentName();

- Devolve o nome do ambiente de &latex; envolvente, ou então, uma string vazia.

    void document.removeEnvironment(bool dentro = false);

- Remove o texto ao redor do ambiente &latex;. Se `inside` for `false`, o texto do ambiente incluindo as marcas envolventes do &latex; `\begin{...}...\end{...}` será removido, caso contrário, será sem estas marcas. Se nenhum parâmetro for fornecido, `inside` é definido como `false`.

    void document.closeEnvironment();

- Insere uma marca de fechamento do ambiente, caso esteja em um ambiente de &latex; aberto na posição atual do cursor.

    void document.closeAllEnvironments();

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

    bool document.hasTexgroup();

- Devolve `true` (verdadeiro) se for encontrado um grupo de &latex; envolvente na posição atual do cursor, caso contrário, devolve `false` (falso).

    String document.texgroup(bool dentro = true);

- Devolve o texto do entorno do grupo &latex;. Se `inside` for `false`, o texto do grupo &latex; incluindo as chaves envolventes `{...}` será devolvido, caso contrário, será sem estas chaves. Se nenhum parâmetro for fornecido, `inside` é definido como `false`. O texto retornado é vazio se nenhum texto envolvente do grupo &latex; for encontrado na posição atual do cursor.

    Range document.texgroupRange(bool dentro = true);

- Devolve o intervalo do grupo &latex; envolvente. Se `inside` for `falso`, o intervalo incluindo as chaves envolventes `{...}` será devolvido, caso contrário, será sem estas chaves. Se nenhum parâmetro for fornecido, `inside` é definido como `false`. Se nenhum grupo for encontrado, `Range.invalid()` é retornado, o que pode ser testado com `Range.isValid()`.

    void document.removeTexgroup(bool dentro = true);

- Remove o texto do grupo &latex; envolvente. Se `inside` for `false`, o texto deste grupo &latex; incluindo as chaves envolventes `{...}` será removido, caso contrário, sem estas chaves. Se nenhum parâmetro for fornecido, `inside` é definido como `false`.

    bool document.hasMathgroup();

- Devolve `true` (verdadeiro) se for encontrado um grupo matemático de &latex; na posição atual do cursor, caso contrário, devolve `false` (falso).

    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 atual do cursor.

    Range document.mathgroupRange();

- Devolve o intervalo do grupo matemático envolvente do &latex;. Se não existir um grupo matemático envolvente, `Range.invalid()` é devolvido, que poderá ser testado com `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; atual.

    Range document.paragraphRange();

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

    void document.removeParagraph();

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

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

- Devolve `true` (verdadeiro) se o `texto` indicado corresponder à posição atual do cursor, caso contrário, devolve `false` (falso).

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

- Devolve `true` (verdadeiro), se a linha inicia com `padrao`, caso contrário, devolve `false` (falso). O argumento `ignorarEspacos` controla se os espaços em branco iniciais são ignorados.

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

- Devolve `true` (verdadeiro), se a linha termina com `padrao`, caso contrário, devolve `false` (falso). O argumento `ignorarEspacos` controla se os espaços em branco iniciais são ignorados.

    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 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 seção de &latex; seguinte.

    void document.gotoPrevSectioning();

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

    void document.gotoLine(int linha);

- Vai para a `linha` indicada.

    void document.insertChapter();

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

    void document.insertSection();

- Insere um comando `\section`. Da mesma maneira que selecionar a entrada de menu LaTeX Criando seções Seção, uma janela será apresentada, aonde você poderá selecionar o título e uma legenda opcional para este comando de criação de seções. 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`. Da mesma maneira que ocorre ao selecionar a entrada de menu &latex;Referências ref uma janela será apresentada, aonde você poderá selecionar a partir de legendas já definidas, que são listadas em uma caixa combinada. 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ário para tornar o texto selecionado ou a linha atual um comentário.

    void document.uncomment();

- Remove os marcadores de comentário da seleção ou da linha atual.

    void document.uppercase();

- Coloca o texto selecionado ou a letra após o cursor em maiúsculo.

    void document.lowercase();

- Coloca o texto selecionado ou a letra após o cursor em minúsculo.

    void document.capitalize();

- Coloca em maiúsculo a primeira letra do texto selecionado ou da palavra atual.

    void document.joinLines();

- Junta as linhas da seleção atual. Duas linhas consecutivas são sempre separadas por um único espaço.

    void document.insertIntelligentNewline();

- Insere uma mudança de linha inteligente (consulte editing_smartnewline).

    void document.insertIntelligentTabulator();

- Insere uma tabulação inteligente (consulte editing_tabulator).

    void document.editBegin();

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

    void document.editEnd();

- Termina um grupo de edição. A última invocação do `editEnd()` (isto é, 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 objetos.

    StringList document.bibitemList();

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

    void document.refreshStructure();

- Atualiza a área da estrutura (consulte navigating).

### A API do &kile;

O objeto global (variável) `kile` é usado para manipular interações de alto nível com o mundo externo, mensagens de entrada e interfaces de janelas. Estas chamadas de API são divididas em subobjetos para estruturar esta parte da programação da API. Conceitualmente, o `kile` é um pouco como a `janela` em um navegador de API.

- `kile.alert`: janelas de mensagens

- `kile.input`: obter dados do usuário

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

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

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

#### Alerta

    void kile.alert.information(String texto, String título);

- Exibe a janela de Informações. O parâmetro `texto` é o texto da mensagem e o `título`, o título da caixa de mensagem. O título padrão é o nome do script.

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

- Exibe uma janela de Alerta. O `texto` é o texto da mensagem e o `titulo` o título da caixa de mensagem. O título padrão é o nome do script.

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

- Exibe uma janela de Erro. O `texto` é o texto da mensagem e o `titulo` o título da caixa de mensagem. O título padrão é o nome do script.

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

- Exibe uma janela de pergunta. O `texto` é o texto da mensagem e o `titulo` o título da caixa de mensagem. O título padrão é o nome do script. O texto retornado é `sim` ou `não`.

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

- Exibe uma janela simples de alerta. O `texto` é o texto da mensagem e o `titulo` o título da caixa de mensagem. O título padrão é o nome do programa. O texto retornado é `continuar` ou `cancelar`.

#### Entrada

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

- Função que permite ao usuário selecionar um item a partir de uma lista, que é exibida como uma caixa de listagem. O `titulo` é o texto que é exibido na barra de título, a `legenda` é o texto que aparece como a legenda da lista e a `lista` é a lista de texto que é inserida na lista.

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

- Função que permite ao usuário selecionar um item a partir de uma lista, que é exibida como uma caixa combinada. O `titulo` é o texto que é exibido na barra de título, a `legenda` é o texto que aparece como a legenda da lista e a `lista` é a lista de texto que é inserida na lista.

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

- Função para obter uma sequência de texto do usuário. 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 usuário. 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);

- Função para obter um inteiro do usuário. O `titulo` é o texto apresentado na barra de título. A `legenda` é o texto que aparece como legenda da caixa de contagem. O `min` e `max` são os valores mínimos e máximos que o usuário poderá escolher. Os valores padrão são `INT_MIN` e `INT_MAX`.

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

- Função para obter um inteiro positivo do usuário. O `titulo` é o texto apresentado na barra de título. A `legenda` é o texto que aparece como legenda da caixa de contagem. O `min` e `max` são os valores mínimos e máximos que o usuário poderá escolher. Os valores padrão são `1` e `INT_MAX`.

#### Assistente

    void kile.wizard.tabular();

- Abre o Assistente de tabelas, que ajuda a criar um ambiente para o efeito (consulte wizard_array).

    void kile.wizard.array();

- Abre o Assistente de listas, que o ajuda a criar um ambiente de listas (consulte wizard_array).

    void kile.wizard.tabbing();

- Abre o Assistente de separadores, que o ajuda a criar um ambiente de separadores (consulte wizard_array).

    void kile.wizard.floatEnvironment();

- Abre o Assistente de flutuantes, que o ajuda a criar um ambiente de elementos flutuantes (consulte wizard_float).

    void kile.wizard.mathEnvironment();

- Abre o Assistente matemático, que o ajuda a criar um ambiente de elementos flutuantes (consulte wizard_math).

    void kile.wizard.postscript();

- Abre o Assistente de ferramentas PostScript, que o ajuda a manipular ou reorganizar documentos em PostScript (consulte wizard_postscript).

#### Script

    String kile.script.name();

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

    String kile.script.caption();

- Devolve um texto que pode ser usado como título da janela de alerta. É parecido com o `Script: scriptname.js`.

#### Arquivo

    Object kile.file.read(String arquivo);

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

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

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

  - status: Fornece o estado do código da operação, que pode ser 0 (sem erros), 1 (falha de acesso) ou 2 (acesso negado). Assim, se nenhum erro ocorrer, o valor de `res.status` ou `res["status"]` será 0.

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

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

    Object kile.file.read();

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

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

- Grava o texto indicado num arquivo. É usado da seguinte forma

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

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

    Object kile.file.write(String texto);

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

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

- Cria uma janela de arquivos modal e devolve o arquivo selecionado ou um texto vazio se nenhum arquivo foi escolhido. Lembre-se de que, com este método, o usuário deverá selecionar um arquivo existente.

  Parâmetros:

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

  - filtro: Um padrão de console ou um filtro de tipos MIME que indica os tipos de arquivos 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 você omitir o `filtro`, todos os arquivos serão exibidos. Se omitir também o `pastaInicial`, a janela usará a pasta atual do documento como ponto inicial.

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

- Cria uma janela de arquivos modal e devolve o arquivo selecionado ou um texto vazio se nenhum arquivo for selecionado. Lembre-se de que, com este método, o usuário não precisa selecionar um arquivo existente. Veja o `getOpenFileName()` para obter uma explicação dos parâmetros.

## Exemplos

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

### Exemplo 1: Substituir o nome do ambiente

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

    var intervalo = document.environmentRange(false);
    if ( intervalo.isValid() ) {
            var nomeAmb = kile.input.getLatexCommand("Insira o ambiente","Nome do novo ambiente:");
            if ( nomeAmb != '' ) {
                    replaceEnvCommand(nomeAmb,intervalo);
            }
    }
    else {
            kile.alert.sorry("Nenhum ambiente LaTeX envolvente encontrado.");
    }

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

            var nomeAmb = document.environmentName();

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

                    document.editBegin();
                    document.replaceText(fimIntervalo,"\\end{"+novoAmb+"}");
                    document.replaceText(iniIntervalo,"\\begin{"+novoAmb+"}");
                    document.editEnd();
            }
    }

### Exemplo 2: Substituir um comando de fonte do &latex;

Substitui o comando de fonte do &latex; envolvente com outro comando de fonte, quando o cursor é posicionado dentro do grupo de texto. A posição relativa do cursor não será alterada. O `\textbf{abc}`, por exemplo, pode ser alterado para `\textit{abc}`.

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

    var intervalo = document.texgroupRange(false);
    if ( intervalo.isValid() ) {
            replaceFontCommand(intervalo);
    }
    else {
            kile.alert.sorry("Nenhum grupo TeX envolvente encontrado.");
    }

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

            document.editBegin();
            view.setCursorPosition(r.start);
            var cmd = document.latexCommand();
            var index = comandosFonte.indexOf(cmd);
            if ( index
    >= 0 ) {
                    var cmdRange = document.latexCommandRange();
                    if ( cmdRange.isValid() ) {
                            var novocomando = kile.input.getListboxItem("Selecione",
                                                        "Selecione o comando de fonte:",buildCmdList(cmd));
                            if ( novocomando != "" ) {
                                    document.replaceText(cmdRange,newcommand);
                                    c.column = c.column - (cmd.length - novocomando.length);
                            }
                    }
    /                view.setCursorPosition(c);
            }
            else {
                    kile.alert.sorry("Nenhum comando de fonte envolvente encontrado.");
            }
            document.editEnd();
    }

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

### Exemplo 3: Envolver o texto selecionado

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

    var intervalo = view.selectionRange();

    if ( intervalo.isValid() ) {
            var cmd = kile.input.getLatexCommand("Selecionar","Selecione o comando LaTeX envolvente:");
            if ( cmd != "" ) {
                    surroundTexCommand("\\"+cmd,range);
            }
    }
    else {
            kile.alert.sorry("Nenhuma seleção encontrada.");
    }

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