&TC.Hollingsworth; &TC.Hollingsworth.mail;
Lisiane
Sztoltz

    lisiane@conectiva.com.br

Tradução
André Marcelo
Alvarenga

    alvarenga@kde.org

Tradução

# Ampliando o &kate;

## Introdução

Como em qualquer editor de texto avançado, o &kate; oferece uma grande variedade de formas para ampliar suas funcionalidades. Você pode criar scripts simples para adicionar funcionalidades com o JavaScript; adicionar funcionalidades melhoradas ao componente de edição com os Plugins do componente de edição; ou adicionar ainda mais funcionalidades ao editor propriamente dito com os plugins do &kate;, escritos em C++ ou os plugins do &pate;, escritos em Python. Finalmente, assim que tiver ampliado as funcionalidades do &kate;, sinta-se a vontade para se juntar a nós e compartilhar as suas melhorias com o mundo!

## Criação de scripts com JavaScript

Desde o &kappname; 3.4, no &kde; 4.4, o componente de edição do &kappname; é facilmente extensível, através da criação de scripts. A linguagem de programação é o ECMAScript (vulgarmente conhecido como JavaScript). O &kappname; suporta dois tipos de scripts: os de recuo e os de linha de comando.

### Scripts de recuo

Scripts de recuo - também conhecidos por recuadores - formatam automaticamente o código-fonte enquanto você digita o texto. Por exemplo, depois de pressionar a tecla Return, o nível de recuo costuma aumentar.

As seções a seguir descrevem, passo-a-passo, como criar o esqueleto de um módulo de recuo simples. Como primeiro passo, crie um novo arquivo `*.js`, chamado de, &eg;, `javascript.js` na pasta pessoal local `$KDEHOME/share/apps/katepart/script/indentation`.

#### O cabeçalho do script de recuo

O cabeçalho do arquivo `javascript.js` está incorporado num comentário e possui o seguinte formato:

    /* kate-script
     * name: JavaScript
     * author: Nome de Exemplo <nome.exemplo@endereco.org>
     * license: BSD
     * revision: 1
     * kate-version: 3.4
     * required-syntax-style: javascript
     * indent-languages: javascript
     * priority: 0
     * i18n-catalog: meucatalogo
     *
     * Uma linha sem um símbolo ':' interrompe o processamento do cabeçalho. Isto é, poderá
     * adicionar mais algum texto aqui como, por exemplo, uma licença detalhada.
     */

Cada item será agora explicado em detalhe:

- `kate-script` [obrigatório]: Este texto tem que aparecer na primeira linha do arquivo `*.js`, caso contrário, o &kappname; irá ignorar o script.

- `name` [obrigatório]: Este é o nome do modo de recuo que aparece no menu Ferramentas Recuar e na janela de configuração.

- `author` [opcional]: O nome e a informação de contato do autor.

- `license` [opcional]: Forma curta da licença, como por exemplo BSD ou LGPLv3.

- `revision` [obrigatório]: A versão do programa. Este número deverá ser aumentado sempre que o programa for modificado.

- `kate-version` [obrigatório]: A versão mínima do &kappname; necessária.

- `required-syntax-style` [opcional]: Lista separa por vírgulas dos estilos de realce de sintaxe necessários. Isto é importante para recuadores que se baseiam em informações de realce no documento. Se uma determinada realce de sintaxe dor especificada, o recuador estará disponível somente quando a realce de sintaxe apropriada estiver ativa. Isto evite um comportamento inesperado causado pelo uso do recuador sem o esquema de realce esperado. Por exemplo, o recuado do Ruby faz uso dos arquivos `ruby.js` e `ruby.xml`.

- `indent-languages` [opcional]: Uma lista, separada por vírgulas, de estilos de sintaxe que este módulo consegue recuar corretamente, &eg;: c++, java.

- `priority` [opcional]: Se existirem vários módulos de recuo adequados para um determinado arquivo de realce, este campo decide qual deverá ser usado por padrão.

- `i18n-catalog` [opcional]: Catálogo de mensagens adicional (arquivo `.po`) carregado para a tradução de endentações de terceiros.

O &kappname; lê todos os pares no formato chave:valor até que não consiga encontrar mais nenhum símbolo de ':'. Isto implica que o cabeçalho poderá conter texto arbitrário, como uma licença, tal como aparece no exemplo.

#### O código-fonte do recuador

Tendo definido o cabeçalho, esta seção explica como funciona a programação de recuadores em si. O esqueleto básico do código parece-se com o seguinte:

    // Necessário para as bibliotecas js do katepart, p.ex., range.js se você usar Range
    require ("range.js");

    caracteresAtivacao = "{}/:;";
    function indent(linha, larguraRecuo, caractere)
    {
        // invocado para cada linha nova (caractere == '\n') e todos os caracteres indicados na
        // variável global 'caracteresAtivacao'. Ao invocar o FerramentasAlinhar
        // a variável 'caractere' está em branco, isto é, caractere == ''.
        //
        // ver também: API de Programação
        return -2;
    }

A função `indent()` tem três parâmetros:

- `linha`: a linha que tem de ser recuada

- `larguraRecuo`: o número de espaços correspondentes a cada recuo

- `caractere`: ou um caractere de mudança de linha (`ch == '\n'`), algum dos caracteres de ativação indicados em `caracteresAtivacao` ou vazio, caso o usuário tenha invocado a ação Ferramentas Alinhar.

O valor devolvido pela função `indent()` define como a linha será recuada. Se o valor devolvido for um número inteiro, é interpretado da seguinte forma:

- valor devolvido `-2`: não fazer nada

- valor devolvido `-1`: mantém o recuo (procura pela linha não-vazia anterior)

- valor devolvido `0`: números >= 0 definem a largura do recuo em espaços

Em alternativa, poderá ser devolvida uma lista com dois elementos:

- `return [ recuo, alinhamento ];`

Nesse caso, o primeiro elemento é a profundidade de recuo, tendo o mesmo significado que os valores especiais. Contudo, o segundo elemento é um valor absoluto que representa uma coluna para o alinhamento. Se este valor for maior que o valor do recuo, a diferença representa um número de espaços a adicionar após o recuo do primeiro parâmetro. Caso contrário, o segundo número será ignorado. A utilização de tabulações e espaços nos recuos é normalmente referida como sendo um modo misto.

Considere o seguinte exemplo: Considerando que são usadas as tabulações para recuar, e que o tamanho da tabulação é de 4. Aqui, o <tab> representa uma tabulação e o '.' representa um espaço:

    1: <tab><tab>xpto("olá",
    2: <tab><tab>......."mundo");

Ao recuar a linha 2, a função `indent()` devolve [8, 15]. Em função disso, são introduzidas duas tabulações para recuar até à coluna 8, e são introduzidos 7 espaços para alinhar o segundo parâmetro com o primeiro, de modo a permanecer alinhado, caso o arquivo seja visto com outro tamanho de tabulação.

Uma instalação padrão do &kde; fornece o &kappname; com vários módulos de recuo. O código-fonte correspondente em JavaScript poderá ser encontrado em `$KDEDIR/share/apps/katepart/script/indentation`.

A criação de um módulo de recuo necessita do recarregamento dos scripts, de modo a ver se as alterações se comportam de forma adequada. Em vez de reiniciar o aplicativo, basta ir para a linha de comando e executar o comando `reload-scripts`.

Se você criar programas úteis, por favor considere a hipótese de contribuir com eles para o Projeto do &kappname;, contactando para isso a lista de correio.

### Programas da Linha de Comando

Como é difícil satisfazer as necessidades de todos, o &kappname; tem suporte a algumas ferramentas auxiliares para manipular rapidamente o texto, usando para isso a linha de comando incorporada. Por exemplo, o comando `sort` está implementado como um script. Esta seção explica como criar arquivos `*.js` que estendem o &kappname; com algumas funções auxiliares arbitrárias.

Os programas da linha de comando estão localizados na mesma pasta que os programas de recuo. Assim, como primeiro passo, crie um arquivo `*.js` novo, chamado `utilitários.js` na pasta pessoal local, em `$KDEHOME/share/apps/katepart/script/commands`.

#### O Cabeçalho do Programa da Linha de Comando

O cabeçalho de cada script da linha de comando está incorporado como um comentário e encontra-se no seguinte formato:

    /* kate-script
     * author: Nome de Exemplo <nome.exemplo@endereco.org>
     * license: BSD
     * revision: 1
     * kate-version: 3.4
     * functions: sort, format-paragraph
     * i18n-catalog: meucatalogo
     *
     * Uma linha sem um símbolo ':' interrompe o processamento do cabeçalho. Isto é, você poderá adicionar
     * algum texto opcional aqui como, por exemplo, uma licença detalhada.
     */

Cada um dos elementos será explicado em detalhe:

- `kate-script` [obrigatório]: Este texto tem que aparecer na primeira linha do arquivo `*.js`, caso contrário, o &kappname; irá ignorar o script.

- `author` [opcional]: O nome e a informação de contato do autor.

- `license` [opcional]: Forma curta da licença, como por exemplo BSD ou LGPLv3.

- `revision` [obrigatório]: A versão do programa. Este número deverá ser aumentado sempre que o programa for modificado.

- `kate-version` [obrigatório]: A versão mínima do &kappname; necessária.

- `functions` [obrigatório]: Uma lista, separada por vírgulas, dos comandos do programa.

- `i18n-catalog` [opcional]: Catálogo de mensagens adicional (arquivo `.po`) carregado para a tradução dos programas de terceiros.

O &kappname; lê todos os pares no formato chave:valor, até que não consiga encontrar mais nenhum símbolo de dois-pontos. Isto implica que o cabeçalho possa conter algum texto arbitrário, como a licença que aparece no exemplo. O valor da chave 'functions' é uma lista, separada por vírgulas, de comandos para a linha de comando. Isso significa que um único script poderá conter um número arbitrário de comandos. Cada uma das funções está disponível no &kappname; através da linha de comando incorporada.

#### O Código-Fonte do Programa

Todas as funções indicadas no cabeçalho terão de estar implementadas no programa. Por exemplo, o arquivo de programa do exemplo acima tem que implementar as duas funções `ordenar` e `formatar-paragrafo`. Todas as funções têm a seguinte sintaxe:

    // bibliotecas necessárias do katepart js, p.ex., range.js se você usar Range
    function <nome>(arg1, arg2, ...)
    {
        // ... implementação, ver também: API de Programação
    }

Os argumentos na linha de comando são passados à função como `arg1`, `arg2`, etc. Para poder indicar a documentação de cada comando, basta implementar a função '`help`', como demonstrado a seguir:

    function help(cmd)
    {
        if (cmd == "sort") {
            return i18n("Ordena o texto selecionado.");
        } else if (cmd == "...") {
            // ...
        }
    }

Executar `help sort` na linha de comando, irá invocar esta função de ajuda com o argumento `cmd` igual ao comando indicado, como &ie;, `cmd == "sort"`. O &kappname; irá assim apresentar o texto devolvido como documentação ao usuário. Certifique-se de traduzir os textos.

##### Associar combinações de teclas

Para poder atribuir atalhos de teclado, o programa terá que fornecer uma função chamada `action` da seguinte forma:

    function action(comando)
    {
        var a = new Object();
        if (comando == "ordenar") {
            a.text = i18n("Ordenar o Texto Selecionado");
            a.icon = "";
            a.category = "";
            a.interactive = false;
            a.shortcut = "";
        } else if (comando == "descerLinhas") {
            // repetir para a ação seguinte
        }
        return a;
    }

O parâmetro `comando` da função indica qual o comando para o qual se pede o atalho de teclado respectivo. Existem vários campos que você terá que indicar no objeto de JavaScript devolvido:

- `a.text` [obrigatório]: O texto que aparece no menu Ferramentas Programas . Certifique-se de usar o `i18n` para as traduções.

- `a.icon` [opcional]: O ícone aparece após ao texto no menu. Todos os nomes de ícones do &kde; poderão ser usados aqui.

- `a.category` [opcional]: Se for indicada uma categoria, o programa aparece num submenu. Certifique-se de usar o `i18n` para as traduções.

- `a.interactive` [opcional]: Se o programa precisa de interação por parte do usuário, configure este valor como `true` (verdadeiro).

- `a.shortcut` [opcional]: A combinação de teclas indicada aqui é o atalho de teclado padrão. Por exemplo: Ctrl+Alt+T. Veja a documentação do Qt para mais detalhes.

Criar um script para a linha de comando requer o recarregamento dos scripts, de modo a ver se as alterações funcionam apropriadamente. Em vez de reiniciar o aplicativo, basta mudar para a linha de comando e executar o comando `reload-scripts`.

Se você criar programas úteis, por favor considere a hipótese de contribuir com eles para o Projeto do &kappname;, contactando para isso a lista de correio.

### API de Programação

A API de criação de scripts aqui apresentada está disponível em todos os scripts, &ie;, os scripts de indentação e os comandos do terminal. As classes `Cursor` e o `Range` são fornecidas por arquivos de bibliotecas no `$KDEDIR/share/apps/katepart/libraries`. Elas serão necessárias, caso queira usar algumas das funções `Document` ou `View` no seu script. Inclua a biblioteca necessária usando:

    // bibliotecas necessárias do katepart js, p.ex., range.js se você usar Range
    require ("range.js");

Para ampliar a API padrão de scripts com suas funções e protótipos próprios, basta criar um arquivo novo na pasta de configuração local do &kde;, em `$KDEHOME/share/apps/katepart/libraries` e incluí-lo no seu script usando:

    require ("myscriptnamehere.js");

Para estender os protótipos existentes, como o `Cursor` ou o `Range`, a forma recomendada é não modificar os arquivos `*.js` globais. Em vez disso, altere o protótipo do `cursor.js` em JavaScript, após o `cursor.js` que é incluído no seu script através do `require`.

#### Cursores e Intervalos

Como o &kappname; é um editor de texto, toda a API de programação é baseada em cursores e intervalos, sempre que possível. Um cursor é um simples tuplo `(linha, coluna)` que representa uma posição de texto no documento. Um Range (Intervalo) corresponde a uma área de texto coberta desde uma posição inicial do cursor até outra posição de fim. A API é explicada em detalhe nas seções a seguir.

##### O Protótipo do Cursor

    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 de 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();`

    Cursor.setPosition(int linha, int coluna);

  Configura a posição do cursor em linha e coluna.

  Desde: &kde; 4.11

    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, localizado 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 for localizado antes do cursor outro,

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

  - `+1`, se este cursor se localizar após o cursor outro.

    bool Cursor.equals(Cursor outro);

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

    String Cursor.toString();

  Devolve o cursor como um texto no formato `Cursor(linha, coluna)`.

##### O Protótipo do Intervalo

    Range();

  Construtor. A invocação de `new Range()` devolve 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 (início, 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 de 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.isEmpty();

  Devolve `true` (verdadeiro), se o cursor de início e de fim forem iguais.

  Exemplo: `var vazio = intervalo.isEmpty();`

  Desde: &kde; 4.11

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

    Range 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 contiver o intervalo Range outro, caso contrário devolve `false` (falso).

    bool Range.containsColumn(int coluna);

  Devolve `true` (verdadeiro), se a coluna estiver 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 estiver 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 intervalo 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 devolve `false` (falso).

    bool Range.overlapsColumn(int coluna);

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

    bool Range.onSingleLine();

  Devolve `true` (verdadeiro), se o intervalo inicia e termina na mesma linha, &ie;, se Range.start.line == Range.end.line.

  Desde: &kde; 4.9

    bool Range.equals(Range outro);

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

    String Range.toString();

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

#### Funções Globais

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

##### Arquivos de leitura e inclusão

    String read(String arquivo);

  Irá procurar pelo arquivo indicado em relação à pasta `katepart/script/files` e irá devolver o seu conteúdo como texto.

    void require(String Arquivo);

  Irá procurar pelo arquivo indicado em relação à pasta `katepart/script/libraries` e avaliá-lo. O `require` está protegido internamente contra inclusões múltiplas do mesmo arquivos.

  Desde: &kde; 4.10

##### Depuração

    void debug(String texto);

  Imprime o texto no `stdout`, mais precisamente no console que lança a aplicação.

##### Tradução

Para um suporte regional completo, existem diversas funções para traduzir os textos nos programas, nomeadamente o `i18n`, o `i18nc`, o `i18np` e o `i18ncp`. Estas funções comportam-se exatamente como as funções de tradução do &kde;.

As funções de tradução convertem os textos indicados ao sistema de traduções do &kde; para o idioma usado no aplicativo. Os textos nos scripts que são desenvolvidos no âmbito do código oficial do &kappname; são automaticamente extraídos e preparados para traduções. Em outras palavras, como programador do &kappname;, você não terá que se preocupar com a extração e tradução das mensagens. Contudo, para programas de terceiros, desenvolvidos fora do &kde;, você terá que extrair e traduzir você mesmo as mensagens. Juntamente com os seus programas, terá que distribuir também um catálogo de traduções que inclui todos os textos traduzidos. Além disso, o cabeçalho do seu programa terá que indicar explicitamente o catálogo a carregar com a indicação do `i18n-catalog`.

    void i18n(String texto, arg1, ...);

  Traduz o texto na língua usada pela aplicação. Os argumentos arg1, ..., são opcionais e usados para substituir os itens `%1`, `%2`, etc.

    void i18nc(String contexto, String texto, arg1, ...);

  Traduz o texto na língua usada pela aplicação. Além disso, o texto do contexto fica visível aos tradutores para que possam dar uma tradução mais adequada. Os argumentos arg1, ..., são opcionais e são usados para substituir os itens de substituição `%1`, `%2`, etc.

    void i18np(String singular, String plural, int número, arg1, ...);

  Traduz tanto o texto singular como o plural para a língua usada pela aplicação, dependendo do número indicado. Os argumentos arg1, ..., são opcionais e usados para substituir os itens de substituição `%1`, `%2`, etc.

    void i18ncp(String contexto, String singular, String plural, intnúmero, arg1, ...);

  Traduz tanto o texto singular como o plural para a língua usada pela aplicação, dependendo do número indicado. Adicionalmente, o texto do contexto é visível para as tradutores, para que possam fornecer uma tradução mais adequada. Os argumentos arg1, ..., são opcionais e são usados para substituir os itens `%1`, `%2`, etc.

#### A API do View

Sempre que um programa está sendo executado, existe uma variável global `view` que representa a área de edição ativa no momento. Segue-se uma lista com todas as funções disponíveis para o View.

    Cursor view.cursorPosition()

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

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

  Altera a posição atual do cursor para uma (linha, coluna) qualquer ou para o cursor indicado.

    Cursor view.virtualCursorPosition();

  Devolve a posição virtual do cursor com cada tabulação a corresponder ao número indicado de espaços, dependente da largura de tabulação atual.

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

  Altera a posição atual do cursor virtual para uma (linha, coluna) qualquer ou para o cursor indicado.

    String view.selectedText();

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

    bool view.hasSelection();

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

    Range view.selection();

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

    void view.setSelection(Range intervalo);

  Altera o texto selecionado para o intervalo indicado.

    void view.removeSelectedText();

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

    void view.selectAll();

  Seleciona todo o texto no documento.

    void view.clearSelection();

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

#### A API do Document

Sempre que está sendo executado um programa, existe uma variável global `document` que representa o documento ativo no momento. Segue-se uma lista com todas as funções disponíveis para o Document.

    String document.fileName();

  Devolve o nome do arquivo do documento, ou então um texto vazio para as janelas de texto ainda por salvar.

    String document.url();

  Devolve o URL completo do documento, ou então um texto vazio para as janelas de texto ainda por salvar.

    String document.mimeType();

  Devolve o tipo MIME do documento, ou então o tipo `application/octet-stream` se não for encontrado qualquer tipo MIME apropriado.

    String document.encoding();

  Devolve a codificação usada atualmente para salvar o arquivo.

    String document.highlightingMode();

  Devolve o modo de realce global usado para todo o documento.

    String document.highlightingModeAt(Cursor pos);

  Devolve o modo de realce usado na posição do cursor indicada do documento.

    Array document.embeddedHighlightingModes();

  Devolve uma lista com os modos de realce incorporados neste documento.

    bool document.isModified();

  Devolve `true` (verdadeiro) se o documento tiver alguma alteração por salvar, caso contrário devolve `false`.

    String document.text();

  Devolve o conteúdo inteiro do documento numa única sequência de texto. As mudanças de linha estão marcadas com o caractere de mudança de linha `\n`.

    String document.text(int daLinha, int daColuna, int paraLinha, int paraColuna);
    String document.text(Cursor de, Cursor para);
    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.

    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.

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

  Devolve a palavra na posição do cursor indicada.

    Range document.wordRangeAt(int linha, int coluna);
    Range document.wordRangeAt(Cursor cursor);

  Devolve o intervalo da palavra na posição indicada do cursor. O intervalo devolvido é inválido (ver Range.isValid()), caso a posição do texto esteja após o fim de uma linha. Se não existir nenhuma palavra no cursor indicado, é devolvido um intervalo vazio.

  Desde: &kde; 4.9

    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 da linha indicada que não seja um espaço em branco. O primeiro caractere encontra-se na coluna 0. Se a linha estiver em branco ou só tiver espaços em branco, o texto devolvido vem vazio.

    String document.lastChar(int linha);

  Devolve o último caractere da linha indicada que não seja um espaço em branco. O primeiro caractere encontra-se na coluna 0. Se a linha estiver em branco ou só tiver espaços em branco, o texto devolvido vem 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).

    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 indicada do cursor, caso contrário devolve `false` (falso).

    bool document.startsWith(int linha, String texto, bool ignorarEspacos);

  Devolve `true` (verdadeiro) se a linha começar por texto, caso contrário devolve `false` (falso). O argumento ignorarEspacos controla se os espaços envolventes são ignorados ou não.

    bool document.endsWith(int linha, String texto, bool ignorarEspacos);

  Devolve `true` (verdadeiro), caso a linha termine em texto, caso contrário devolve `false` (falso). O argumento ignorarEspacos controla se os espaços envolventes são ignorados.

    bool document.setText(String texto);

  Altera o texto do documento por inteiro.

    bool document.clear();

  Limpa o texto no documento por inteiro.

    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.

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

  Insere o texto na posição do cursor indicada. Devolve `true`, em caso de sucesso, ou `false` (falso), se o documento estiver apenas para leitura.

    bool document.removeText(int daLinha, int daColuna, int paraLinha, int paraColuna);
    bool document.removeText(Cursor de, Cursor para);
    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.insertLine(int linha, String texto);

  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(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.wrapLine(int linha, int coluna);
    bool document.wrapLine(Cursor cursor);

  Reparte a linha na posição indicada pelo cursor. Devolve `true` (verdadeiro) em caso de sucesso ou `false` (falso) se, &eg;, a linha < 0.

  Desde: &kde; 4.9

    void document.joinLines(int linhaInicial, int linhaFinal);

  Junta as linhas de linhaInicial até linhaFinal. Duas linhas de texto sucessivas estão sempre separadas por um espaço em branco.

    int document.lines();

  Devolve o número de linhas do documento.

    int document.length();

  Devolve o número de caracteres do documento.

    int document.lineLength(int linha);

  Devolve o comprimento da linha.

    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, &ie;, esta chamada pode ser encadeada.

    void document.editEnd();

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

    int document.firstColumn(int linha);

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

    int document.lastColumn(int linha);

  Devolve a última coluna que não esteja em branco para a linha indicada. Se só existirem espaços em branco na 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.

    bool document.isInWord(String caractere, int atributo);

  Devolve `true` (verdadeiro), caso o caractere e atributo indicados possam fazer parte de uma palavra, caso contrário devolve `false` (falso).

    bool document.canBreakAt(String caractere, int atributo);

  Devolve `true` (verdadeiro) se o caractere indicado com o atributo indicado for adequado para mudar de linha, caso contrário devolve `false`.

    bool document.canComment(int atributoInicial, int atributoFinal);

  Devolve `true` (falso), caso um intervalo que começa e termina com os atributos indicados possa ser comentado; caso contrário, devolve `false` (falso).

    String document.commentMarker(int atributo);

  Devolve o marcador de comentários, usado em linhas únicas, para um determinado atributo.

    String document.commentStart(int atributo);

  Devolve o marcador de início de comentários, usado em linhas múltiplas, para um determinado atributo.

    String document.commentEnd(int atributo);

  Devolve o marcador de fim de comentários, usado em linhas múltiplas, para um determinado atributo.

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

  Devolve o atributo na posição do cursor indicada.

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

  Devolve `true` (verdadeiro), se o atributo na posição do cursor indicada for igual a atributo, caso contrário devolve `false` (falso).

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

  Devolve o nome do atributo como um texto legível. Isto é igual ao nome `itemData` dos arquivos de realce de sintaxe.

    bool document.isAttributeName(int linha, int coluna, String nome);
    bool document.isAttributeName(Cursor cursor, String nome);

  Devolve `true` (verdadeiro), se o nome do atributo, numa dada posição do cursor, corresponder ao nome indicado, caso contrário devolve `false` (falso).

    String document.variable(String chave);

  Devolve o valor da variável do documento identificada pela chave. Se a variável do documento não existir, o valor devolvido é um texto em branco.

    String document.setVariable(String chave, String valor);

  Define o valor da variável do documento solicitada pela chave. Devolve o valor da variável alterada.

  Veja também: Variáveis de documento do Kate

  Desde: &kde; 4.8

    int document.firstVirtualColumn(int linha);

  Devolve a coluna virtual do primeiro caractere não-nulo na linha indicada, ou então `-1` se a linha estiver em branco ou só tiver caracteres de espaços em branco.

    int document.lastVirtualColumn(int linha);

  Devolve a coluna virtual do último caractere não-nulo na linha indicada, ou então `-1` se a linha estiver em branco ou só tiver caracteres de espaços em branco.

    int document.toVirtualColumn(int linha, int coluna);
    int document.toVirtualColumn(Cursor cursor);
    Cursor document.toVirtualCursor(Cursor cursor);

  Converte a posição do cursor real para uma posição virtual, retornando um int ou um objeto Cursor.

    int document.fromVirtualColumn(int linha, int colunaVirtual);
    int document.fromVirtualColumn(Cursor cursorVirtual);
    Cursor document.fromVirtualCursor(Cursor cursorVirtual);

  Converte a posição virtual do cursor para uma posição do cursor real, retornando um int ou um objeto Cursor.

    Cursor document.anchor(int linha, int coluna, Char caractere);
    Cursor document.anchor(Cursor cursor, Char caractere);

  Pesquisa para trás pelo caractere indicado, começando na posição do cursor indicada. Por exemplo, se for passado o '(', como caractere, esta função irá devolver a posição do '(' de abertura. Isto implica uma contagem das referências, &ie;, os outros '(...)' são ignorados.

    Cursor document.rfind(int linha, int coluna, String texto, int atributo = -1);
    Cursor document.rfind(Cursor cursor, String texto, int atributo = -1);

  Pesquisa para trás pelo texto indicado, com o atributo apropriado. O argumento atributo é ignorado se for igual a `-1`. O cursor devolvido é inválido, caso o texto não tenha sido encontrado.

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

  Devolve o estilo padrão que é usado na posição do cursor indicada.

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

  Devolve `true` (verdadeiro) se o atributo na posição do cursor indicada não for igual a todos os seguintes estilos: `dsComment`, `dsString`, `dsRegionMarker`, `dsChar`, `dsOthers`.

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

  Devolve `true` se o atributo do caractere na posição do cursor for `dsComment`; caso contrário devolve `false`.

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

  Devolve `true` (verdadeiro) se o atributo do caractere na posição do cursor for `dsString`, caso contrário devolve `false` (falso).

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

  Devolve `true` (verdadeiro) se o atributo do caractere na posição do cursor for `dsRegionMarker`, caso contrário devolve `false` (falso).

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

  Devolve `true` (verdadeiro) se o atributo do caractere na posição do cursor for `dsChar`, caso contrário devolve `false` (falso).

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

  Devolve `true` (verdadeiro) se o atributo do caractere na posição do cursor for `dsOthers`, caso contrário devolve `false` (falso).

## Extensões do componente de edição

As Extensões do componente de edição ampliam o KatePart, o componente de edição de texto avançado, que é usado em muitos aplicativos do &kde;, como o &kate;, o &kwrite;, o Kile e o KDevelop. A criação de um plugin do componente de edição permitir-lhe ampliar a funcionalidade do editor em todos estes programas.

Para começar, leia o Tutorial do plugin do KTextEditor no &kde; TechBase. Para aprender ainda mais, leia o Tutorial Avançado, também disponível na TechBase.

Você poderá encontrar a documentação completa da API nas referências de API do &kde;.

## Plugins do aplicativo &kate; (C++)

Os Plugins do aplicativo Kate ampliam as funcionalidades do editor &kate; propriamente dito, usando a mesma linguagem de programação em que o &kate; é escrito - C++.

Para começar, leia o Tutorial de criação de um plugin na página Web do &kate;. Também existe um clássico plugin de exemplo Olá mundo!, que vem incluído no código-fonte do &kate;.

## Plugins em Python do &pate;

Os Plugins do &pate; também permitem ampliar as funcionalidades do &kate; da forma que desejar, usando a linguagem de programação Python.

Para começar, leia o guia de desenvolvimento de plugins em Python na página Web do &kate;.

Você também poderá acessar as referências da API na tela de Configuração do &pate;.