# 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 à seleção ou à linha atual, se não existir texto selecionado, se os comentários são suportados pelo formato do texto que você está editando.

As regras de como o comentário é feito são feitas nas definições de sintaxe; assim, se o realce de sintaxe não é usado, as ações de comentar/descomentar não são possíveis.

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

Se um marcador de linha única estiver disponível, é preferível comentar linhas simples onde for aplicável, pois isto ajuda a evitar problemas com comentários aninhados.

Ao remover marcadores de comentários, textos sem comentários devem ser selecionados; ao remover marcadores de comentários de múltiplas linhas de uma seleção, qualquer espaço em branco fora do marcador é ignorado.

Para colocar marcações de comentários, use a opção do menu Ferramentas Comentar ou o atalho de teclado relacionado, que por padrã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 padrão é o &Ctrl;&Shift;D.

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

O componente de edição do Kate possui uma linha de comando interna, que lhe permite efetuar várias ações a partir de uma interface mínima. A linha de comando é um campo de texto no fundo da área de edição onde, para mostrá-la, você poderá selecionar a opção Ver Alternar para Linha de Comando ou usar o atalho (que é, por padrão, o F7). O editor oferece um conjunto de comandos, tal como está documentado abaixo, sendo oferecidos mais comandos através de 'plugins'.

Para executar um comando, pressione a tecla Return. A linha de comando irá indicar se foi bem sucedida e, provavelmente, irá mostrar uma mensagem. Se você inseriu na linha de comando pressionando F7, ele ocultar-se-á automaticamente, ao fim de alguns segundos. Para limpar a mensagem e inserir um comando novo, pressione F7 de novo.

A linha de comando possui um sistema de ajuda embutido, podendo inserir o comando `help` para iniciá-lo. Para ver uma lista com todos os comandos disponíveis, invoque o comando `help list`; para ver a ajuda sobre um determinado comando, faça `help `comando``.

A linha de comando possui um histórico embutido, como tal, o usuário poderá reutilizar os comandos já digitados. Para navegar no histórico, use as teclas Cima e Baixo. Ao mostrar os comandos do histórico, a parte do argumento do comando será selecionada, o que lhe permite sobrepor facilmente os argumentos.

### Comandos Padrão da Linha de Comando

#### Comandos para Configurar o Editor

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

#### Tipos de argumento

BOOLEANO

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

INTEIRO

- Um número inteiro

TEXTO

- Um texto

    set-tab-widthINTEIRO largura

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

    set-indent-widthINTEIRO largura

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

    set-word-wrap-columnINTEIRO largura

- Configura a largura da linha para uma quebra como tendo `largura` colunas. Isto é usado se você tiver o seu texto sendo quebrado automaticamente.

    set-icon-borderBOOLEANO ativar

- Configura a visibilidade da borda dos ícones.

    set-folding-markersBOOLEANO ativar

- Configura a visibilidade da área de marcadores de dobra do código.

    set-line-numbersBOOLEANO ativar

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

    set-replace-tabsBOOLEANO ativar

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

    set-remove-trailing-spaceBOOLEANO ativar

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

    set-show-tabsBOOLEANO ativar

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

    set-indent-spacesBOOLEANO ativar

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

    set-mixed-indentBOOLEANO ativar

- Se estiver ativo, o &kate; 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 otimizados para usar tantos caracteres TAB quantos possíveis.

  Quando for executado, este comando irá ativar 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, no momento da execução.

    set-word-wrapBOOLEANO ativar

- Ativa a quebra de linha dinâmica, de acordo com o parâmetro `ativar`

    set-replace-tabs-saveBOOLEANO ativar

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

    set-remove-trailing-space-saveBOOLEANO ativar

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

    set-indent-modenome

- 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 'cstyle', 'csands', 'xml', 'python', 'varindent' e 'none'.

    set-highlightrealce

- 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.

#### Comandos de edição

Estes comandos modificam o documento atual.

    indent

- Indenta as linhas selecionadas ou a linha atual.

    unindent

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

    cleanindent

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

    comment

- Insere marcações de comentários para fazer da seleção, linhas selecionadas ou da linha atual 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 seleção, linhas selecionadas ou da linha atual, de acordo com o formato de texto definido pela definição do realce de sintaxe do documento.

    kill-line

- Remove a linha atual.

    replacepadrãosubstituiçã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 aspas simples ou duplas. 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 selecionada.

`r`

- Faz uma pesquisa por uma determinada expressão regular. Se estiver ativo, 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ão para substituir a próxima ocorrência.

`w`

- Faz uma correspondência apenas com palavras inteiras.

    dateformato

- 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 a seguir 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).
  `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".

    charidentificador

- Este comando permite que você insira caracteres literais através de suas identificações numéricas, em decimal, octal ou hexadecimal. Para usá-lo, abra o diálogo de Edição de Comando e digite `char: [número]` na caixa de entrada e clique em OK.

  ##### exemplos do comando `char`

  Entrada: `char:234`

  Resultado: `ê`

  Entrada: `char:0x1234`

  Resultado: `ሴ`

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

- Este comando faz um sed como operação de procura/substituição na linha atual, ou em um arquivo inteiro (`%s///`).

  Em resumo, é procurado o texto que combine com o padrão de busca , a expressão regular entre a primeira e a segunda barra, e quando é encontrado, a parte que combina com o texto é substituída pela expressão entre a metade e a última parte da string. Os parênteses no padrão de busca criam referências anteriores, isto é, o comando lembra qual parte procurada combinou no parênteses; estas strings podem ser reutilizadas no padrão de substituição, referidas como `\1` para o primeiro conjunto de parênteses, `\2` para o segundo e assim por diante.

  Para procurar por um caractere literal `(` ou `)`, você precisa usar o caractere de escape, que é o caractere de barra invertida: `\(\)`

  Se você 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.

  ##### Substituindo texto na linha atual

  Seu compilador parou, dizendo a você que a classe `minhaClasse`, mencionada na linha 3902 do seu arquivo fonte, não está definida.

  "Droga!" você pensa, é claro que é `MinhaClasse`. Você vai para a linha 3902, e em vez de tentar encontrar a palavra no texto, você lança o Diálogo de Edição de Comando, digita `s/minhaclasse/MinhaClasse/i`, clica no botão OK, salva o arquivo e compila – com sucesso, sem erros.

  ##### Substituindo texto no arquivo inteiro

  Imagine que você tem um arquivo, onde está mencionado a string Senhorita Jensen várias vezes, quando alguém vem e lhe diz que ela casou com o Senhor Jones. Você quer, é claro, substituir toda ocorrência de Senhorita Jensen por Senhora Jones.

  Entre na linha de comando e digite o comando `%s/Srª Silva/Srª Braga/`, pressionando 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 abaixo).

  Suponha que você possui a seguinte linha:

      void MinhaClasse::DoStringOps( String      &foo, String &bar String *p, int  &a, int &b )

  Agora, você pode perceber que este não é um código bom, e decidir que deseja usar a palavra-chave `const` para todos os argumentos address of, aqueles caracterizados pelo operador & em frente ao nome do argumento. Você poderia também simplificar o espaço em branco, pois assim existiria somente um caractere de espaço em branco entre cada palavra.

  Abra o Diálogo de Edição de Comando, e digite `s/\s+(\w+)\s+(&)/ const \1 \2/g` e clique no botão OK. O caractere `g` no final da expressão faz com que a expressão regular recompile cada combinação, para recuperar as referências de volta.

  Saída `void MinhaClasse::DoStringOps( const String &foo, const String &bar String *p, const int &a, const int &b )`

  Missão completa! Agora, o que aconteceu? Bem, procuramos por espaços em branco (`\s+`) seguidos por um ou mais caracteres alfabéticos(`\w+`) seguidos por mais espaços em branco (`\s+`) seguidos por um E comercial, e no processo é salvo o pedaço alfabético e o E comercial para reutilização na operação de substituição. Quando substituímos a parte relacionada da nossa linha, com um espaço em branco, seguido por const, seguido por um espaço em branco, seguido por nosso pedaço alfabético (`\1`) seguido por um espaço em branco, em por fim, seguido por nosso E comercial salvo (`\2`)

  Em alguns casos, a parte alfabética foi String, em alguns int, assim, usar a classe de caractere `\w` e o quantificador `+` provê uma vantagem considerável.

#### Comandos de navegação

    gotoINT linha

- Este comando vai para a linha indicada.

    findpadrão

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

  O comando de procura poderá ser configurado adicionando 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 selecionada.

`r`

- Faz uma pesquisa por uma determinada expressão regular. Se estiver ativo, 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.

    ifindpadrão

- Este comando oferece uma procura à-medida-que-digita. Você poderá configurar o comportamento da procura adicionando 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.

## Usando o Desdobramento de Código

O desdobramento ou dobragem de código permite-lhe ocultar partes de um documento no editor, tornando mais simples analisar globalmente arquivos grandes. No &kate;, as regiões desdobráveis são calculadas com base nas regras das 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, ative 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 da tela, mostra uma visão gráfica sobre as regiões que poderão ser recolhidas ou expandidas, com símbolos +/- para indicar a operação possível numa determinada região: um '-' significa que a região é expandida; enquanto clicar no '-' irá recolher a região, clicar no '+' irá exibí-la.

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

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

## Programando o componente do editor com Javascript

### Introdução

Desde a versão 2.5, o componente de edição do &kate; suporta a programação em ECMA Script, também conhecido como JavaScript.

Os programas só poderão ser usados através da linha de comando embutida. Os requisitos são que o arquivo esteja colocado numa pasta em que o &kate; o consiga encontrar, em conjunto com um arquivo .desktop opcional que define as propriedades relacionadas. Algumas pastas válidas são a `katepart/scripts` nas pastas de dados do &kde;. Você poderá encontrar as pastas de dados executando o comando `kde-config `--path` `data`` Você terá pelo menos uma pasta do sistema e uma pessoal. Claro que os programas na pasta de dados do sistema estão disponíveis para todos os usuários do sistema, enquanto os das pastas pessoais só estão disponíveis para o respectivo usuário.

Esta funcionalidade é experimental e poderá vir a mudar durante os desenvolvimentos futuros.

Sabemos que muitos usuários poderão ficar desapontados, uma vez que não poderão adicionar os seus programas ao menu ou atribuir atalhos a eles. Infelizmente, só no futuro provavelmente isso será possível.

Também não é possível passar argumentos aos seus programas ainda. Tenha paciência, que isso será implementado em breve no futuro ;)

### A API de JavaScript do Kate

Aqui está listado o conjunto completo de funções e propriedades disponíveis nos objetos `document` e `view`. Além disso, você poderá também usar todos os objetos-padrão, como o `Math`, o `String`, o `Regex` e assim por diante.

Quando um programa é executado, o objeto `document` é o documento atual, enquanto o `view` é a janela atual.

Os tipos dos argumentos não são, obviamente, usados no JavaScript neste momento, servindo apenas para indicar que tipo de valor as funções estão esperando.

### Funções Globais

`debug( ``texto``) [função]`

- ### parâmetros

  - `texto` a mensagem a exibir

  Envia o texto para o STDERR com o `kdDebug()`. É usada uma área de saída dedicada para o texto, o qual será antecedido de `Kate (KJS Scripts):`

### A API do `document`

`document.attribute( ``linha`` , ``coluna`` ); [função]`

- ### Parâmetros

  - `uint linha` A linha da posição onde encontrar o atributo.

  - `uint coluna` A coluna da posição onde encontrar o atributo.

  Devolve o ID numérico do atributo para a posição do documento [`linha`,`coluna`]. O atributo representa a aparência ou estilo visual do texto, e é usado também para calcular o realce de sintaxe para uma parte específica do texto, em formatos mixtos como o HTML ou o PHP.

`document.canBreakAt( `Char c`, `uint atributo` ); [função]`

- ### Parâmetros

  - `c` O caracter a testar

  - `atributo` O atributo na posição do `c`.

  Devolve se é permitido quebrar a linha num caracter 'c' com o atributo 'atributo'. O resultado é decidido através da pesquisa do realce que contém o atributo, para o qual os caracteres permitem a quebra de linha.

`document.canComment( `uint atributo_inicio`, `uint atributo_fim` ); [função]`

- ### Parâmetros

  - `atributo_inicio` O atributo no início do intervalo para converter num comentário.

  - `atributo_fim` O atributo no fim do intervalo para converter num comentário.

  Devolve se o atributo_inicio e o atributo_fim pertencem ao mesmo sistema de realce de sintaxe. Se sim, é seguro.

  #### Usando o canComment

      if ( document.canComment( document.attribute(1,0), document.attribute(5,0) ) ) {
          // o 1,0 e o 5,0 pertencem ao mesmo sistema de realce de sintaxe
      }

`document.clear(); [função]`

- Limpa o documento.

`document.commentStart( `uint atributo` ); [função]`

- ### Parâmetros

  - `atributo` O atributo do texto para qual deseja obter o texto do 'commentStart'.

  Devolve o texto necessário para iniciar um comentário para várias linhas com um texto e um atributo, ou um texto vazio se não forem suportados comentários em várias linhas para esse texto.

`document.commentMarker( `uint atributo` ); [função]`

- ### Parâmetros

  - `atributo` O atributo do texto para o qual deseja obter o texto do 'commentMarker'

  Devolve o texto necessário para marcar o resto da linha como um comentário com um texto e um atributo, ou um texto vazio se não forem suportados comentários numa única linha para esse texto.

`document.commentEnd( `uint atributo` ); [função]`

- ### Parâmetros

  - `atributo` O atributo do texto para o qual deseja obter o texto do 'commentEnd'

  Devolve o texto necessário para terminar um comentário para várias linhas com um texto e um atributo, ou um texto vazio se não forem suportados comentários em várias linhas para esse texto.

`document.editBegin(); [função]`

- Inicia um grupo de edição. Todas as ações feitas até à chamada do editEnd() serão agrupadas como uma ação anulável.

`document.editEnd(); [função]`

- Termina um grupo de edição.

`document.highlightMode; [propriedade:apenas leitura]`

- O nome do modo de realce do documento, como por exemplo JavaScript ou C++. Se não estiver definido qualquer modo de realce de sintaxe, o valor é igual a None. Lembre-se que terá de usar o nome em Inglês, no caso de ser diferente da versão traduzida.

`document.indentMode; [propriedade:apenas leitura]`

- O nome do modo de indentação do documento, como por exemplo `normal` ou `cstyle`. Lembre-se que, se não estiver definido qualquer modo de indentação, o valor é igual a `none`.

`document.indentWidth; [propriedade:apenas leitura]`

- A largura da indentação do documento. Isto é usado se você indentar com espaços.

`document.insertLine( `uint linha`, `string texto` ); [função]`

- ### Parâmetros

  - `linha` número de linha do documento

  - `texto` o texto a inserir

  Insere uma linha nova com o texto `texto` na linha `linha`.

`document.insertText( `uint linha`, `uint coluna`, `string texto` ); [função]`

- ### Parâmetros

  - `linha` o número de linha

  - `coluna` o número da coluna

  - `texto` o texto a inserir

  Insere o texto `texto` na linha `linha` e coluna `coluna`.

document.length(); [função]

- Devolve o tamanho do documento em 'bytes'.

`document.lines(); [função]`

- Devolve o número de linhas do documento.

document.mixedIndent; [propriedade:apenas leitura]

- Um booleano que lhe diz se a opção 'mixed-indent' está ativa para o documento. Se sim, a indentação é otimizada para conter uma mistura de tabulações e espaços, como acontece no editor Emacs.

document.removeLine( `uint linha` ); [função]

- ### Parâmetros

  - `linha` o número de linha

  Remove a linha especificada do documento.

`document.removeText( `uint linhaInicial`, `colunaInicial`, `uint linhaFinal`, `uint colunaFinal` ); [função]`

- ### Parâmetros

  - `linhaInicial` corresponde à linha inicial

  - `colunaInicial` corresponde à coluna inicial

  - `linhaFinal` corresponde à linha final

  - `colunaFinal` corresponde à coluna final

  Remove o intervalo de texto da linha `linhaInicial` e coluna `colunaInicial` até à linha `linhaFinal` e coluna `colunaFinal`.

`document.setText( `string texto` ); [função]`

- ### Parâmetros

  - `texto` o texto do documento

  Configura o conteúdo inteiro do documento como `texto`.

`document.spaceIndent; [propriedade:apenas leitura]`

- Um booleano que indica se o 'space-indent' está ativo para o documento. Se for o caso, o documento é indentado com larguraIndentacao espaços por nível, caso contrário, a indentação corresponde a uma tabulação por nível.

`document.textFull(); [função]`

- Devolve o conteúdo completo do documento. Se o texto se espalhar por várias linhas, o carácter de mudança de linha é o `\n`.

`document.textLine( uint linha ); [função]`

- ### Parâmetros

  - `linha` a linha

  Devolve o texto da linha `linha`.

`document.textRange( `uint linhaInicial`, `uint colunaInicial`, `uint linhaFinal`, `uint colunaFinal` ); [função]`

- ### Parâmetros

  - `linhaInicial` corresponde à linha inicial

  - `colunaInicial` corresponde à coluna inicial

  - `linhaFinal` corresponde à linha final

  - `colunaFinal` corresponde à coluna final

  Devolve o intervalo de texto indicado. Se o intervalo se espalhar por várias linhas, o caracter de mudança de linha é o `\n`.

### A API do `view`

`view.clearSelection(); [função]`

- Remove a seleção de todo o texto.

`view.cursorColumn(); [função]`

- Devolve a coluna atual do cursor (os caracteres TAB são expandidos).

`view.cursorColumnReal(); [função]`

- Devolve a coluna real do cursor (os caracteres TAB contam como um).

`view.cursorLine(); [função]`

- Devolve a linha atual do cursor.

`view.hasSelection(); [função]`

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

`view.removeSelectedText(); [função]`

- Remove o texto selecionado, se a janela tiver alguma seleção.

`view.selectAll(); [função]`

- Seleciona todo o texto.

`view.selection(); [função]`

- Devolve o texto selecionado. Se a seleção se espalhar por várias linhas, o caracter de mudança de linha é o `\n`.

`view.selectionEndColumn; [propriedade:apenas leitura]`

- Devolve a coluna final da seleção.

`view.selectionEndLine; [propriedade:apenas leitura]`

- Devolve a linha final da seleção.

`view.selectionStartColumn; [propriedade:apenas leitura]`

- Devolve a coluna inicial da seleção.

`view.selectionStartLine; [propriedade:apenas leitura]`

- Devolve a linha inicial da seleção.

`view.setCursorPosition( `uint linha`, `uint coluna` ); [função]`

- ### Parâmetros

  - `linha` Indica a linha para o cursor.

  - `coluna` Indica a coluna para o cursor.

  Configura a posição atual do cursor na janela como sendo [`linha`, `col`]. A posição do cursor é a nível visual, isto é, um caracter TAB conta como `tab-width` espaços, dependendo da posição dentro da linha. A posição do cursor é tornada visível. Tanto a linha como a coluna começam em zero.

`view.setCursorPositionReal( `uint linha`, `uint coluna` ); [função]`

- ### Parâmetros

  - `linha` Indica a linha para o cursor.

  - `coluna` Indica a coluna para o cursor.

  Configura a posição atual do cursor na janela como sendo [`linha`, `col`]. A posição do cursor é a nível do texto, isto é, um caracter TAB conta como 1. A posição do cursor é tornada visível. Tanto a linha como a coluna começam em zero.

`view.setSelection( `uint linhaInicial`, `uint colunaInicial`, `uint linhaFinal`, `uint colunaFinal` ); [função]`

- ### Parâmetros

  - `linhaInicial` corresponde à linha inicial

  - `colunaInicial` corresponde à coluna inicial

  - `linhaFinal` corresponde à linha final

  - `colunaFinal` corresponde à coluna final

  Configura a seleção desde a linha `linhaInicial` e coluna `colunaInicial` até à linha `linhaFinal` e coluna `colunaFinal`.

#### Um programa de exemplo

Como exemplo, será criado um pequeno programa que converte o texto selecionado para maiúsculas. É óbvio que se deverá ver primeiro se existe texto selecionado, para que se possa obter o texto, mudar a capitalização e depois substituir pelo novo. Uma implementação possível seria do género:

    if ( view.hasSelection() )
    {
      // seleção para maiúsculas
      column = view.selectionStartColumn;
      line = view.selectionStartLine;

      selection = view.selection().toUpperCase();

      document.editBegin();
      view.removeSelectedText();
      document.insertText( line, column, selection );
      document.editEnd();
    }

Para agrupar esta ação em conjunto, para que possam ser anuladas com uma única ativação do Desfazer, as linhas

    view.removeSelectedText()

e

    document.insertText()

são encapsuladas com um

    document.editBegin()

e

    document.editEnd()

.

#### Um arquivo `.desktop` de exemplo

Aqui está um arquivo .desktop de exemplo que acompanha o programa acima.

    # Exemplo de um arquivo .desktop
    [Desktop Entry]
    Encoding=UTF-8
    Name=Kate Part JavaScript Uppercase
    Comment=Script to uppercase the selection
    X-Kate-Command=uppercase-selection
    X-Kate-Help=<p>Usage: <code>uppercase-selection</code></p>

Como você pode ver, você pode definir a codificação, definir um nome, comentário, um texto de ajuda com o X-Kate-Help e o nome da linha de comando com o X-Kate-Command. Os itens Name, Comment e X-Kate-Help são traduzidos automaticamente para outros idiomas pelas equipes de traduções do KDE, se os arquivos estiverem no repositório de SVN do KDE.

#### Colocando tudo junto

O &kate; irá procurar nas pastas de programas (ver acima) por arquivos `*.js`. Para cada um deles, verifica se existe um arquivo `.desktop` correspondente, como por exemplo, maiusculas.js corresponderia a maiusculas.desktop.

Se não for encontrado um arquivo `.desktop`, o programa será registrado na linha de comando com o nome do arquivo sem o '.js' final, para que, no nosso exemplo, fosse `maiusculas`. Se o nome do comando for aceitável e não necessitar de funcionalidades extras de um arquivo `.desktop`, não será necessário um arquivo `.desktop`.

Se o arquivo `.desktop` existir, o 'katepart' irá ler o nome sob o qual o programa será registrado, a partir do item do '.desktop' X-Kate-Command, como por exemplo X-Kate-Command=uppercase-selection.