# Ferramentas Avançadas de Edição

## Comentar/Descomentar

Os comandos Comentar e Descomentar, disponíveis no menu Ferramentas permitem-lhe adicionar ou remover marcações de comentários à selecção ou à linha actual, se não estiver texto seleccionado. Os comentários são suportados pelo formato do texto que você está a editar.

As regras de como os comentários são feitos estão descritas nas definições da sintaxe; por isso, se o realce de sintaxe não é usado, o comentar/descomentar não é possível.

Alguns formatos definem comentários para linhas únicas, outros suportam comentários para várias linhas e ainda outros suportam ambos. Se não estiverem disponíveis os comentários para várias linhas, o acto de comentar uma selecção que não inclui por completo a sua última linha não é possível.

Se estiver disponível uma marcação para linhas únicas, o acto de comentar linhas únicas é preferível quando aplicável, dado que evita os problemas com os comentários aninhados.

Ao remover as marcações de comentários, não deve ser escolhido texto sem comentários. Ao retirar as marcações de comentários de várias linhas de uma selecção, todos os espaços em branco fora das marcações de comentários são ignorados.

Para colocar marcações de comentários, use a opção do menu Ferramentas Comentar ou a sequência de teclado relacionada, que por omissão é &Ctrl;D.

Para remover marcações de comentários, use a opção do menu Ferramentas Descomentar ou o atalho de teclado relacionado, que por omissão é o &Ctrl;&Shift;D.

## A Linha de Comandos do Componente de Edição

O componente de edição do &kappname; tem uma linha de comandos interna, que lhe permite efectuar várias acções a partir de uma interface mínima. A linha de comandos é um campo de texto no fundo da área de edição onde, para a mostrar, poderá seleccionar a opção Ver Mudar para a Linha de Comandos ou usar o atalho (que é, por omissão, o F7). O editor oferece um conjunto de comandos, tal como está documentado em baixo, sendo oferecidos mais comandos através de 'plugins'.

Para executar um comando, carregue na tecla Return. A linha de comandos irá indicar se foi bem sucedida e, provavelmente, irá mostrar uma mensagem. Se você introduziu a linha de comandos ao carregar em F7, ele esconder-se-á automaticamente, ao fim de alguns segundos. Para limpar a mensagem e introduzir um comando novo, carregue em F7 de novo.

A linha de comandos tem um sistema de ajuda incorporado, pelo que poderá introduzir o comando `help` para iniciar. Para ver uma lista com todos os comandos disponíveis, invoque o comando `help list`; para ver a ajuda sobre um dado comando, faça `help `comando``.

A linha de comandos tem um histórico incorporado, como tal, o utilizador poderá reutilizar os comandos já escritos. Para navegar no histórico, use as teclas Cima e Baixo. Ao mostrar os comandos do histórico, a parte de argumento do comando será seleccionada, o que lhe permite sobrepor facilmente os argumentos.

### Comandos Normais da Linha de Comandos

### Tipos de argumento

BOOLEANO

- Isto é usado com os comandos que activam ou desactivam certas coisas. Os valores válidos são o `on`, `off`, `true`, `false`, `1` ou `0`.

INTEIRO

- Um número inteiro.

TEXTO

- Um texto separado por plicas (') ou aspas (") quando tiver espaços.

#### Comandos para Configurar o Editor

Estes comandos são oferecidos pelo componente do editor e permitem-lhe configurar apenas o documento e a janela activos. Isto poderá ser útil se quiser usar uma configuração diferente da predefinida como, por exemplo, na indentação.

    set-tab-widthINTEGER largura

- Configura a largura da tabulação como sendo `largura`.

    set-indent-widthINTEGER largura

- Configura a largura da indentação como `largura`. Só é usado se o utilizador indentar com espaços.

    set-word-wrap-columnINTEGER largura

- Configura a largura da linha para uma mudança restrita como tendo `largura` colunas. Isto é usado se você tiver o seu texto a ser repartido automaticamente.

    set-icon-borderBOOLEAN activar

- Configura a visibilidade do contorno dos ícones.

    set-folding-markersBOOLEAN activar

- Configura a visibilidade da área de marcadores de dobragem/desdobramento do código.

    set-line-numbersBOOLEAN activar

- Configura a visibilidade da área de números de linha.

    set-replace-tabsBOOLEAN activar

- Se estiver activo, as tabulações são substituídas por espaços, à medida que você vai escrevendo.

    set-remove-trailing-spaceBOOLEAN activar

- Se estiver activo, os espaços finais serão removidos quando o cursor abandonar uma dada linha.

    set-show-tabsBOOLEAN activar

- Se estiver activo, os caracteres de tabulação e espaços estarão visíveis através de um pequeno ponto.

    set-show-indentBOOLEAN activar

- Se estiver activo, a indentação será visualizada como uma linha pontilhada vertical.

    set-indent-spacesBOOLEAN activar

- Se estiver activo, o editor irá indentar com `largura-indentação` espaços por cada nível de indentação, em vez de usar o carácter TAB.

    set-mixed-indentBOOLEAN activar

- Se estiver activo, o &kappname; irá usar uma mistura de TABs e espaços para a indentação. Cada nível de indentação irá ter um tamanho de `largura-indentação`, enquanto os restantes níveis de indentação serão optimizados para usar tantos caracteres TAB quantos possíveis.

  Quando for executado, este comando irá activar a indentação com espaços e, se a largura de indentação não estiver definida, corresponderá a metade da `largura-tabulação` do documento, na altura da execução.

    set-word-wrapBOOLEAN activar

- Activa a mudança de linha dinâmica, de acordo com o parâmetro `activar`

    set-replace-tabs-saveBOOLEAN activar

- Quando estiver activo, as tabulações serão substituídas por espaços em branco, sempre que o documento for gravado.

    set-remove-trailing-space-saveBOOLEAN activar

- Quando estiver activo, os espaços finais serão removidos de cada linha, sempre que o documento for gravado.

    set-indent-modeSTRING nome

- Configura o modo de indentação automática como `nome`. Se o `nome` não for conhecido, o modo é configurado como 'none' (nenhum). Os modos válidos são o 'none', 'normal', 'cstyle', 'haskell', 'lilypond', 'lisp', 'python', 'ruby' e 'xml'.

    set-auto-identBOOLEAN programa

- Activa ou desactiva a indentação automática.

    set-highlightSTRING realce

- Configura o sistema de realce de sintaxe para o documento. O argumento deverá ser um nome de realce válido, como pode ser visto no menu Ferramentas Realce. Este comando oferece uma lista de completação automática para o seu argumento.

    reload-scripts

- Volta a carregar todos os programas em JavaScript usados pelo Kate, incluindo os módulos de indentação e programas da linha de comandos.

    set-modeSTRING modo

- Escolhe o esquema do tipo de ficheiro do documento actual.

    nn[oremap]STRING original STRING associado

- Associa a sequência de teclas `original` a `associado`.

#### Comandos de edição

Estes comandos modificam o documento actual.

    indent

- Indenta as linhas seleccionadas ou a linha actual.

    unindent

- Remove um nível de indentação das linhas seleccionadas ou da linha actual.

    cleanindent

- Limpa a indentação das linhas seleccionadas ou da linha actual, de acordo com a configuração de indentação no documento.

    comment

- Insere marcações de comentários para fazer da selecção, linhas seleccionadas ou da linha actual um comentário, de acordo com o formato de texto definido pela definição do realce de sintaxe para o documento.

    uncomment

- Remove os marcadores de comentários da selecção, linhas seleccionadas ou da linha actual, de acordo com o formato de texto definido pela definição do realce de sintaxe do documento.

    kill-line

- Remove a linha actual.

    replace STRING padrão STRING substituição

- Substitui o texto correspondente ao `padrão` por `substituição`. Se você quiser incluir espaços em branco no `padrão`, deverá colocar tanto o `padrão` como a `substituição` entre plicas ou aspas. Se os argumentos não estiverem entre estes caracteres, a primeira palavra é usada como `padrão` e o resto como a `substituição`. Se a `substituição` estiver em branco, cada ocorrência do `padrão` será removida.

  Você poderá configurar opções para modificar a procura, adicionando dois pontos (:), seguidos de uma ou mais letras, onde cada uma representa uma configuração, o que corresponderá ao formato `replace:opções padrão substituição`. As opções disponíveis são:

  `b`

- Procura para trás.

`c`

- Procura a partir da posição do cursor.

`e`

- Procura apenas na área seleccionada.

`r`

- Faz uma pesquisa por uma dada expressão regular. Se estiver activo, você poderá usar o `\N`, onde o N é um número que representa as capturas no texto de substituição.

`s`

- Faz uma pesquisa com distinção entre maiúsculas e minúsculas.

`p`

- Pede permissões para substituir a próxima ocorrência.

`w`

- Faz uma correspondência apenas com palavras inteiras.

    dateSTRING formato

- Insere um texto de data/hora, tal como está definido pelo `formato` indicado, ou com o formato aaaa-MM-dd hh:mm:ss, se não for indicada qualquer formatação. As traduções seguintes são feitas quando for interpretado o `formato`:

  `d` | O dia, como um número sem um zero inicial (1-31).
  `dd` | O dia, como um número com um zero inicial (01-31).
  `ddd` | O nome do dia abreviado, no formato regional (p.ex. 'Seg'..'Dom').
  `dddd` | O nome do dia completo, no formato regional (p.ex. 'Segunda'..'Domingo').
  `M` | O mês, como um número sem um zero inicial (1-12).
  `MM` | O mês, como um número com um zero inicial (01-12).
  `MMMM` | O nome do mês por extenso, no formato regional (p.ex. 'Janeiro'..'Dezembro').
  `MMM` | O nome do mês abreviado, no formato regional (p.ex. 'Jan'..'Dez').
  `aa` | O ano, como um número de dois algarismos (00-99).
  `aaaa` | O ano, como um número de quatro algarismos (1752-8000).
  `h` | As horas sem um zero inicial (0..23 ou 1..12 no caso do formato AM/PM).
  `hh` | As horas com um zero inicial (00..23 ou 01..12 no caso do formato AM/PM).
  `m` | Os minutos sem um zero inicial (0..59).
  `mm` | Os minutos com um zero inicial (00..59).
  `s` | Os segundos sem um zero inicial (0..59).
  `ss` | Os minutos com um zero inicial (00..59).
  `z` | Os milisegundos sem um zero inicial (0..999).
  `zzz` | Os milisegundos com zeros iniciais (000..999).
  `AP` | Usar o formato de horas AM/PM. O AP será substituído por "AM" ou por "PM".
  `ap` | Usar o formato de horas am/pm. O AP será substituído por "am" ou por "pm".

    charSTRING identificador

- Este comando permite-lhe introduzir caracteres literais pelo seu identificador numérico em decimal, octal ou hexadecimal. Para o usar, invoque a Janela do Comando de Edição e escreva `char: [number]` no campo de texto, carregando depois em OK.

  ##### Exemplos do `char`

  Introdução: `char:234`

  Resultado: `ê`

  Introdução: `char:0x1234`

  Resultado: `ሴ`

`s///[ig]` `%s///[ig]`

- Este comando efectua uma operação de pesquisa e substituição à 'sed' na linha actual ou em todo o ficheiro (`%s///`).

  Em resumo, o texto é percorrido à procura de uma sequência que corresponda ao padrão de busca, a expressão regular entre a primeira e a segunda barra, e quando for encontrada uma correspondência, esta é substituída pela expressão entre a parte do meio e a parte final do texto. Os parêntesis no padrão de busca criam referências anteriores, ou seja, o comando recorda qual a parte que correspondeu aos parêntesis; estas sequências podem ser reutilizadas no padrão de substituição, sendo referenciadas como `\1` para o primeiro conjunto de parêntesis, `\2` para o segundo e assim por diante.

  Para procurar por um `(` ou `)`, é necessário escapá-lo, usando uma barra invertida: `\(\)`

  Se puser um `i` no fim da expressão, a correspondência não fará distinção entre maiúsculas ou minúsculas. Se, por outro lado, puser um `g` no fim, todas as ocorrências do padrão serão substituídas, caso contrário, só será substituída a primeira ocorrência.

  ##### Substituir texto na linha actual

  O seu amigo compilador parou, indicando que a classe `myClass` representada na linha 3902 do ficheiro de código não está definida.

  "Bolas!" pensa você, é óbvio que é `MyClass`. Vá à linha 3902 e, em vez de tentar procurar a palavra no texto, invoque a Janela de Comando de Edição, escreva `s/myclass/MyClass/i`, carregue no botão OK, grave o ficheiro e compile – com sucesso, sem o erro.

  ##### Substituir texto no ficheiro inteiro

  Imagine que tem um ficheiro, no qual menciona uma Srª Silva várias vezes, quando vem alguém e lhe diz que ela se casou com o Sr. Pires. Irá querer, obviamente, substituir todas as ocorrências de Srª Silva por Srª Pires.

  Entre na linha de comandos e escreva no campo de texto o comando `%s/Srª Silva/Srª Pires/`, carregando em RETURN para terminar.

  ##### Um Exemplo Mais Avançado

  Este exemplo tira partido das referências anteriores assim como das classes de palavras (se você não souber o que isso é, baseie-se na documentação referida em baixo).

  Imagine que tem a seguinte linha:

      void MinhaClass::OperacaoTexto( String      &xpto, String &xpto2 String *p, int  &a, int &b )

  Agora, chega à conclusão que este não é um código bonito, e decide que quer usar a palavra `const` para todos os endereços dos argumentos, os quais se caracterizam pelo operador & à frente do nome do argumento. Também irá querer simplificar os espaços em branco, de modo a que haja apenas um espaço entre cada palavra.

  Lance a Janela de Comando de Edição, escreva: `s/\s+(\w+)\s+(&)/ const \1 \2/g` e carregue no botão OK. O `g`, no fim da expressão, recompila a expressão para cada correspondência para poupar as referências anteriores.

  Resultado: `void MinhaClasse::OperacaoTexto( const String &xpto, const String &xpto2 String *p, const int &a, const int &b )`

  Missão cumprida! Agora, o que se passou? Bem, procurou alguns espaços em branco (`\s+`) seguidos de um ou mais caracteres alfabéticos (`\w+`) seguidos por mais alguns espaços em branco (`\s+`) e um 'e' comercial, gravando durante o processo a sequência alfabética e o 'e' comercial para os reutilizar na operação de substituição. Assim, substituiu-se a parte correspondente da linha em questão por um espaço em branco seguido de const, um espaço em branco e depois pela sequência alfabética (`\1`) seguida de um espaço em branco e o '&' guardado (`\2`)

  Agora, em alguns dos casos, a sequência alfabética era String, em outras era int, de modo que a utilização da classe de caracteres `\w` e do quantificador `+` foram uma ajuda preciosa.

    sort

- Ordena o texto seleccionado ou o documento inteiro.

    natsort

- Ordena naturalmente o texto seleccionado ou o documento inteiro.

  ##### `sort` vs. `natsort`

  O `sort(a10, a1, a2)` devolverá `a1, a10, a2`

  O `natsort(a10, a1, a2)` devolverá `a1, a2, a10`

    moveLinesDown

- Desce as linhas seleccionadas.

    moveLinesUp

- Sobe as linhas seleccionadas.

    uniq

- Remove as linhas duplicadas do texto seleccionado ou do documento inteiro.

    rtrim

- Remove os espaços finais do texto seleccionado ou do documento inteiro.

    ltrim

- Remove os espaços iniciais do texto seleccionado ou do documento inteiro.

    joinSTRING separador

- Junta as linhas seleccionadas ou o documento inteiro. Opcionalmente, recebe um parâmetro que define um separador, como por exemplo: ``join` ', '`

    rmblank

- Remove todos os espaços em branco do texto seleccionado ou do documento inteiro.

    unwrap

- Remove as mudanças de linha do texto seleccionado ou do documento inteiro.

    eachSTRING programa

- Dada uma função em JavaScript como argumento, invoca-a para a lista de linhas seleccionadas e substitui-as pelo valor devolvido por essa chamada.

  ##### Juntar as linhas seleccionadas

  ``each` 'function(linhas){return linhas.join(", ")}'`

  Ou, de forma mais resumida:

  ``each` 'linhas.join(", ")'`

    filterSTRING programa

- Dada uma função em JavaScript como argumento, invoca-a para a lista de linhas seleccionadas e remove as que devolvam um valor falso para essa chamada.

  ##### Remover as linhas em branco

  ``filter` 'function(1){return 1.length > 0;}'`

  Ou, de forma mais resumida:

  ``filter` 'linha.length > 0'`

    mapSTRING programa

- Dada uma função em JavaScript como argumento, invoca-a para a lista de linhas seleccionadas e substitui a linha pelo valor da chamada.

  ##### Remover as linhas em branco

  ``map` 'function(linha){return linha.replace(/^s+/,"");}'`

  Ou, de forma mais resumida:

  ``map` 'linha.replace(/^s+/,"")'`

    duplicateLinesUp

- Duplica as linhas seleccionadas acima da selecção actual.

    duplicateLinesDown

- Duplica as linhas seleccionadas abaixo da selecção actual.

#### Comandos de navegação

    gotoINT linha

- Este comando vai para a linha indicada.

    grep STRING padrão

- Procura no documento pela expressão regular `padrão`. Para mais informações, veja as regular-expressions

    findSTRING padrão

- Este comando vai para a primeira ocorrência do `padrão`, de acordo com a configuração. As ocorrências seguintes poderão ser encontradas com a opção Editar Procurar o Seguinte (o atalho por omissão é o F3).

  O comando de procura poderá ser configurado se adicionar dois-pontos, seguidos de uma ou mais opções, sendo o formato `find:opções padrão`. São suportadas as seguintes opções:

  `b`

- Procura para trás.

`c`

- Procura a partir da posição do cursor.

`e`

- Procura apenas na área seleccionada.

`r`

- Faz uma pesquisa por uma dada expressão regular. Se estiver activo, você poderá usar o `\N`, onde o N é um número que representa as capturas no texto de substituição.

`s`

- Faz uma pesquisa com distinção entre maiúsculas e minúsculas.

`w`

- Faz uma correspondência apenas com palavras inteiras.

    ifindSTRING padrão

- Este comando oferece uma procura à-medida-que-escreve. Você poderá configurar o comportamento da procura se adicionar dois-pontos (:), seguidos de uma ou mais opções, como se segue: `ifind:opções padrão`. As opções permitidas são

  `b`

- Procura para trás.

`r`

- Faz uma procura por uma expressão regular.

`s`

- Faz uma pesquisa com distinção entre maiúsculas e minúsculas.

`c`

- Procura a partir da posição do cursor.

#### Comandos das Funções Básicas de Edição (Estas dependem da aplicação em que o componente de edição é usado)

    w

- Grava o documento actual.

    wa

- Grava todos os documentos abertos de momento.

    q

- Fecha o documento actual.

    qa

- Fecha todos os documentos abertos.

    wq

- Grava e fecha o documento actual.

    wqa

- Grava e fecha todos os documentos abertos de momento.

    x

- Grava e fecha o documento actual, somente se tiver sido alterado.

    x

- Grava e fecha todos os documentos abertos de momento, somente se tiverem sido alterados.

    bp

- Vai para o documento anterior na lista de documentos.

    bn

- Vai para o documento seguinte na lista de documentos.

    new

- Abre um documento numa janela dividida horizontalmente.

    vnew

- Abre um documento numa janela dividida verticalmente.

    e

- Volta a carregar o documento actual, caso tenha sido alterado no disco.

    enew

- Edita um novo documento.

    print

- Abre a janela de impressão para imprimir o documento actual.

## Usar o Desdobramento de Código

O desdobramento ou dobragem de código permite-lhe esconder partes de um documento no editor, tornando mais simples analisar globalmente ficheiros grandes. No &kappname;, as regiões desdobráveis são calculadas com base nas regras nas definições de realce de sintaxe, como tal só está disponível em alguns formatos - tipicamente em código-fonte de programas, código em XML e semelhantes. A maioria das definições de realce que suportam o desdobramento de código também lhe permitem definir manualmente regiões desdobráveis, tipicamente com as palavras-chave `BEGIN` e `END`.

Para usar a funcionalidade de desdobramento de código, active os marcadores com a opção Ver Mostrar as Marcações de Dobragem, se não estiverem já visíveis. A área de Marcações de Dobragem, no lado esquerdo do ecrã, mostra uma vista gráfica sobre as regiões que poderão ser recolhidas ou expandidas, com símbolos de triângulos para indicar a operação possível numa dada região: um triângulo para baixo significa que a região é expandida, enquanto se carregar nele irá recolher a região e ficará então visível um triângulo para a direita em alternativa.

Estão disponíveis onze comandos para manipular o estado das regiões dobradas; para tal, veja a documentação do menu.

As linhas dobradas são recordadas quando fechar um ficheiro; assim, quando o reabrir, os nós dobrados irão continuar dessa forma. Isto aplica-se também às operações de recarregamento.

Se não quiser usar a funcionalidade de desdobramento do código, poderá desactivar a opção Mostrar as marcações de dobragem (se disponíveis) na página de Aparência da configuração do editor.

## Extender o &kappname; com Programas

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 programas. A linguagem de programação é o ECMAScript (vulgarmente conhecido como JavaScript). O &kappname; suporta dois tipos de programas: os de indentação e os de linha de comandos.

### Programas de Indentação

Programas de indentação - também conhecidos por indentadores - formatam automaticamente o código-fonte enquanto escreve o texto. Por exemplo, depois de carregar na tecla Return, o nível de indentação costuma aumentar.

As seguintes secções descrevem, passo-a-passo, como criar o esqueleto de um módulo de indentação simples. Como primeiro passo, crie um novo ficheiro `*.js`, chamado por exemplo `javascript.js` na pasta pessoal local `$KDEHOME/share/apps/katepart/script/indentation`.

#### O Cabeçalho do Programa de Indentação

O cabeçalho do ficheiro `javascript.js` está incorporado num comentário e tem o seguinte formato

    /* kate-script
     * name: JavaScript
     * author: Nome de Exemplo <nome.exemplo@um.endereco.org>
     * license: BSD
     * revision: 1
     * kate-version: 3.4
     * type: indentation
     * required-syntax-style: javascript
     * indent-languages: javascript
     * priority: 0
     * i18n-catalog: meu-catalogo
     *
     * Uma linha sem o 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 de aparecer na primeira linha do ficheiro `*.js`, caso contrário o &kappname; irá ignorar o programa.

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

- `author` [opcional]: O nome e a informação de contacto 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]: Uma lista, separada por vírgulas, dos estilos de realce de sintaxe obrigatórios. Isto é importante para os módulos de indentação que se baseiam em alguma informação específica de realce no documento. Se for indicado um estilo de sintaxe obrigatório, o módulo só ficará disponível quando estiver o realce apropriado seleccionado. Isto evita algum comportamento indefinido causado pela utilização da indentação sem o esquema de realce esperado. Por exemplo, a indentação de Ruby tira partido disto nos ficheiros `ruby.js` e `ruby.xml`.

- `indent-languages` [opcional]: Uma lista, separada por vírgulas, de estilos de sintaxe que este módulo consegue indentar correctamente, p.ex.: c++, java.

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

- `i18n-catalog` [opcional]: Catálogo de mensagens adicional (ficheiro `.po`) carregado para a tradução de indentaçõ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 da Indentação

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

    require("range.js");

    caracteresActivacao = "{}/:;";
    function indent(linha, larguraIndentacao, caracter)
    {
        // invocado para cada linha nova (caracter == '\n') e todos os caracteres indicados na
        // variável global 'caracteresActivacao'. Ao invocar o FerramentasAlinhar
        // a variável 'caracter' está em branco, i.e. caracter == ''.
        //
        // 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 indentada

- `larguraIndentacao`: o número de espaços correspondentes a cada indentação

- `caracter`: ou um carácter de mudança de linha (`ch == '\n'`), algum dos caracteres de activação indicados em `caracteresActivacao` ou vazio, caso o utilizador tenha invocado a acção Ferramentas Alinhar.

O valor devolvido pela função `indent()` define como é que a linha será indentada. 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 a indentação (procura pela linha não-vazia anterior)

- valor devolvido `0`: números >= 0 definem a largura de indentação em espaços

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

- `return [ indentação, alinhamento ];`

Nesse caso, o primeiro elemento é a profundidade de indentação, 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 de indentação, a diferença representa um número de espaços a adicionar após a indentação do primeiro parâmetro. Caso contrário, o segundo número será ignorado. A utilização de tabulações e espaços na indentação é normalmente referida como sendo um modo misto.

Considere o seguinte exemplo: Assuma que usa as tabulações para indentar, 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 indentar a linha 2, a função `indent()` devolve [8, 15]. Em função disso, são introduzidas duas tabulações para indentar 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 ficheiro seja visto com outro tamanho de tabulação.

Uma instalação predefinida do KDE fornece o &kappname; com vários módulos de indentação. 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 indentação necessita que actualize os programas, de modo a ver se as alterações se comportam de forma adequada. Em vez de reiniciar a aplicação, basta ir para a linha de comandos e invocar o comando `reload-scripts`.

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

### Programas da Linha de Comandos

Como é difícil satisfazer as necessidades de todos, o &kappname; suporta algumas ferramentas auxiliares para manipular rapidamente o texto, usando para tal a linha de comandos incorporada. Por exemplo, o comando `sort` está implementado como um programa. Esta secção explica como criar ficheiros `*.js` que extendem o &kappname; com algumas funções auxiliares arbitrárias.

Os programas da linha de comandos estão localizados na mesma pasta que os programas de indentação. Como tal, como primeiro passo, crie um ficheiro `*.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 Comandos

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

    /* kate-script
     * author: Nome de Exemplo <nome.exemplo@um.endereco.org>
     * license: BSD
     * revision: 1
     * kate-version: 3.4
     * type: commands
     * functions: sort, format-paragraph
     * i18n-catalog: meu-catalogo
     *
     * Uma linha sem o símbolo ':' interrompe o processamento do cabeçalho. Isto é, 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 de aparecer na primeira linha do ficheiro `*.js`, caso contrário o &kappname; irá ignorar o programa.

- `author` [opcional]: O nome e a informação de contacto 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 (ficheiro `.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 comandos. Isto significa que um único programa poderá conter um conjunto arbitrário de comandos. Cada uma das funções está disponível no &kappname; através da linha de comandos 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 ficheiro de programa do exemplo acima tem de implementar as duas funções `ordenar` e `formatar-paragrafo`. Todas as funções têm a seguinte sintaxe:

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

    function <nome>(arg1, arg2, ...)
    {
        // ... implementação, ver também: API de Programação
    }

Os argumentos na linha de comandos são passados à função como `arg1`, `arg2`, etc. Para poder fornecer a documentação para cada comando, basta implementar a função '`help`' da seguinte forma:

    function help(comando)
    {
        if (comando == "ordenar") {
            return i18n("Ordena o texto seleccionado.");
        } else if (cmd == "...") {
            // ...
        }
    }

Se executar `help ordenar` na linha de comandos, irá invocar esta função 'help' com o argumento `comando` configurado com o comando indicado, i.e. `comando == "ordenar"`. O &kappname; irá então apresentar o texto devolvido como documentação para o utilizador. Certifique-se que traduz os textos.

##### Associar Combinações de Teclas

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

    function action(comando)
    {
        var a = new Object();
        if (comando == "ordenar") {
            a.text = i18n("Ordenar o Texto Seleccionado");
            a.icon = "";
            a.category = "";
            a.interactive = false;
            a.shortcut = "";
        } else if (comando == "descerLinhas") {
            // repetir para a acçã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 terá de indicar no objecto de JavaScript devolvido:

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

- `a.icon` [opcional]: O ícone aparece a seguir ao texto no menu. Todos os nomes de ícones do KDE poderão ser aqui usados.

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

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

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

Criar um programa para a linha de comandos obriga a actualizar os programas, de modo a ver se as alterações funcionam apropriadamente. Em vez de reiniciar a aplicação, basta mudar para a linha de comandos e invocar o comando `reload-scripts`.

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

### API de Programação

A API de programação aqui apresentada está disponível em todos os programas, i.e. os programas de indentação e os comandos da consola. O `Cursor` e o `Range` são fornecidos através de ficheiros de bibliotecas no `$KDEDIR/share/apps/katepart/libraries`. Se quiser usá-los no seu programa, o que será necessário para usar algumas das funções do `Document` ou do `View`, inclua por favor a biblioteca necessária, usando:

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

Para extender a API-padrão de programação com funções e protótipos próprio, basta criar um ficheiro novo na pasta de configuração local do KDE, em `$KDEHOME/share/apps/katepart/libraries` e inclua-a no seu programa, usando:

    require ("nome-do-meu-programa.js");

Para extender os protótipos existentes, como o `Cursor` ou o `Range`, a forma recomendada é não modificar os ficheiros `*.js` globais. Em vez disso, altere o protótipo do `Cursor` em JavaScript, após o `cursor.js` que é incluído no seu programa com o `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 secções seguintes.

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

    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 a seguir ao 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.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 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 semi-aberto `[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 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 intervalo `outro` partilharem 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 começar e acabar na mesma linha.

  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 secção apresenta todas as funções globais.

##### Ler & Incluir os Ficheiros

    String read(String ficheiro);

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

    void require(String ficheiro);

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

##### Depuração

    void debug(String texto);

- Imprime o `texto` no `stdout`, mais precisamente na consola 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 exactamente 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 a língua usada na aplicação. Os textos nos programas que são desenvolvidos no âmbito do código oficial do &kappname; são automaticamente extraídos e preparados para traduções. Por outras palavras, como programador do &kappname;, não terá de se preocupar com a extracção e tradução das mensagens. Contudo, para programas de terceiros, desenvolvidos fora do KDE, terá de extrair e traduzir você mesmo a as mensagens. Em conjunto com os seus programas, terá de distribuir também um catálogo de traduções que inclui todos os textos traduzidos. Para além disso, o cabeçalho do seu programa terá de 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. Para ale´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, 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. 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á a ser executado, existe uma variável global `view` que representa a área de edição activa no momento. Segue-se uma lista com todas as funções disponíveis para o View.

    Cursor view.cursorPosition()

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

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

- Altera a posição actual 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 actual.

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

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

    String view.selectedText();

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

    bool view.hasSelection();

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

    Range view.selection();

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

    void view.setSelection(Range intervalo);

- Altera o texto seleccionado para o intervalo indicado.

    void view.removeSelectedText();

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

    void view.selectAll();

- Selecciona o texto por inteiro no documento.

    void view.clearSelection();

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

#### A API do Document

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

    String document.fileName();

- Devolve o nome do ficheiro do documento, ou então um texto vazio para as janelas de texto ainda por gravar.

    String document.url();

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

    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 actualmente para gravar o ficheiro.

    String document.highlightingMode();

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

    String document.highlightingModeAt(Cursor posição);

- 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 algumas alterações por gravar, 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 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.

    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 com 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 carácter na posição do cursor indicada.

    String document.firstChar(int linha);

- Devolve o primeiro carácter da `linha` indicada 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 só tiver espaços em branco, o texto devolvido vem vazio.

    String document.lastChar(int linha);

- Devolve o último carácter da `linha` indicada 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 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 carácter 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 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.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 p.ex. 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 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.

    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 caracter, int atributo);

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

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

- Devolve `true` (verdadeiro) se o `carácter` 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 ficheiros 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);

- Altera o valor da variável do documento identificada pela `chave`. Devolve o valor da variável alterada.

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

  Desde: KDE 4.8

    int document.firstVirtualColumn(int linha);

- Devolve a coluna virtual do primeiro carácter 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 carácter 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, devolvendo um objecto inteiro ou um 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, devolvendo um objecto inteiro ou um Cursor.

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

- Pesquisa para trás pelo carácter indicado, começando na posição do cursor indicada. Por exemplo, se for passado o '(', como carácter, esta função irá devolve a posição do '(' de abertura. Isto implica uma contagem das referências, i.e., 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 predefinido 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 carácter 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 carácter 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 carácter 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 carácter 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 carácter na posição do cursor for `dsOthers`, caso contrário devolve `false` (falso).