<chapter id="advanced-editing-tools">
<chapterinfo>
<authorgroup>
<author
>&Anders.Lund; &Anders.Lund.mail;</author>
<author
>&Dominik.Haumann; &Dominik.Haumann.mail;</author>
<othercredit role="translator"
><firstname
>Lisiane</firstname
><surname
>Sztoltz</surname
><affiliation
><address
><email
>lisiane@conectiva.com.br</email
></address
></affiliation
><contrib
>Tradução</contrib
></othercredit
> 
</authorgroup>
</chapterinfo>
<title
>Ferramentas Avançadas de Edição</title>

<sect1 id="advanced-editing-tools-comment">

<title
>Comentar/Descomentar</title>

<para
>Os comandos Comentar e Descomentar, disponíveis no menu <guimenu
>Ferramentas</guimenu
> 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.</para>

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

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

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

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

<para
><indexterm
><primary
>comentar</primary
></indexterm
> Para colocar marcações de comentários, use a opção do menu <menuchoice
><guimenu
>Ferramentas</guimenu
><guimenuitem
>Comentar</guimenuitem
></menuchoice
> ou o atalho de teclado relacionado, que por padrão é <keycombo action="simul"
>&Ctrl;<keycap
>D</keycap
></keycombo
>.</para>

<para
><indexterm
><primary
>descomentar</primary
></indexterm
> Para remover marcações de comentários, use a opção do menu <menuchoice
><guimenu
>Ferramentas</guimenu
><guimenuitem
>Descomentar</guimenuitem
></menuchoice
> ou o atalho de teclado relacionado, que por padrão é o <keycombo action="simul"
>&Ctrl;&Shift;<keycap
>D</keycap
></keycombo
>.</para>

</sect1>

<sect1 id="advanced-editing-tools-commandline">
<title
>A Linha de Comando do Componente de Edição</title>

<para
>O componente de edição do &kappname; 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 <menuchoice
><guimenu
>Ver</guimenu
><guimenuitem
>Alternar para Linha de Comando</guimenuitem
></menuchoice
> ou usar o atalho (que é, por padrão, o <keycombo action="simul"
><keycap
>F7</keycap
></keycombo
>). O editor oferece um conjunto de comandos, tal como está documentado abaixo, sendo oferecidos mais comandos através de plugins.</para>

<para
>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 <keycap
>F7</keycap
>, ele ocultar-se-á automaticamente, ao fim de alguns segundos. Para limpar a mensagem e inserir um comando novo, pressione <keycap
>F7</keycap
> de novo.</para>

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

<para
>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 <keycap
>Cima</keycap
> e <keycap
>Baixo</keycap
>. Ao mostrar os comandos do histórico, a parte do argumento do comando será selecionada, o que lhe permite sobrepor facilmente os argumentos.</para>

<sect2 id="advanced-editing-tools-commandline-commands">
<title
>Comandos Padrão da Linha de Comando</title>

<variablelist>
<title
>Tipos de argumento</title>

<varlistentry>
<term
>BOOLEANO</term>
<listitem
><para
>Isto é usado com os comandos que ativam ou desativam certas coisas. Os valores válidos são o <userinput
>on</userinput
>, <userinput
>off</userinput
>, <userinput
>true</userinput
>, <userinput
>false</userinput
>, <userinput
>1</userinput
> ou <userinput
>0</userinput
>.</para
></listitem>
</varlistentry>

<varlistentry>
<term
>INTEIRO</term>
<listitem
><para
>Um número inteiro.</para
></listitem>
</varlistentry>

<varlistentry>
<term
>TEXTO</term>
<listitem
><para
>Uma string separada por aspas simples (') ou aspas (") quando conter espaços.</para
></listitem>
</varlistentry>

</variablelist>



<sect3 id="advanced-editing-tools-commandline-commands-configure">
<title
>Comandos para configurar o Editor</title>

<para
>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, no recuo. </para>

<variablelist>

<varlistentry>
<term
><cmdsynopsis
><command
>set-tab-width</command
><arg choice="req"
>INTEIRO largura</arg
></cmdsynopsis
></term>
<listitem
><para
>Configura a largura da tabulação como sendo <userinput
>largura</userinput
>.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-indent-width</command
><arg choice="req"
>INTEIRO largura</arg
></cmdsynopsis
></term>
<listitem
><para
>Configura a largura do recuo como <userinput
>largura</userinput
>. Só é usado se o usuário recuar com espaços.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-word-wrap-column</command
><arg choice="req"
>INTEIRO largura</arg
></cmdsynopsis
></term>
<listitem
><para
>Configura a largura da linha para uma quebra como tendo <userinput
>largura</userinput
> colunas. Isto é usado se você tiver o seu texto sendo quebrado automaticamente.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-icon-border</command
><arg choice="req"
>BOOLEANO ativar</arg
> </cmdsynopsis
></term>
<listitem
><para
>Configura a visibilidade da borda dos ícones.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-folding-markers</command
><arg choice="req"
>BOOLEANO ativar</arg
></cmdsynopsis
></term>
<listitem
><para
>Configura a visibilidade da área de marcadores de dobra do código.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-line-numbers</command
><arg choice="req"
>BOOLEANO ativar</arg
></cmdsynopsis
></term>
<listitem
><para
>Configura a visibilidade da área de números de linha.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-replace-tabs</command
><arg choice="req"
>BOOLEANO ativar</arg
></cmdsynopsis
></term>
<listitem
><para
>Se estiver ativo, as tabulações são substituídas por espaços, à medida que você vai digitando. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-remove-trailing-space</command
><arg choice="req"
>BOOLEANO ativar</arg
></cmdsynopsis
></term>
<listitem
><para
>Se estiver ativo, os espaços finais serão removidos quando o cursor abandonar uma determinada linha.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-show-tabs</command
><arg choice="req"
>BOOLEANO ativar</arg
></cmdsynopsis
></term>
<listitem
><para
>Se estiver ativo, os caracteres de tabulação e espaços estarão visíveis através de um pequeno ponto.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-show-indent</command
><arg choice="req"
>BOOLEANO ativar</arg
></cmdsynopsis
></term>
<listitem
><para
>Se estiver ativo, o recuo será visualizado por uma linha tracejada vertical.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-indent-spaces</command
><arg choice="req"
>BOOLEANO ativar</arg
></cmdsynopsis
></term>
<listitem
><para
>Se estiver ativo, o editor irá recuar com <option
>largura-recuo</option
> espaços por cada nível de recuo, em vez de usar o caractere TAB.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-mixed-indent</command
><arg choice="req"
>BOOLEANO ativar</arg
></cmdsynopsis
></term>
<listitem
><para
>Se estiver ativo, o &kappname; irá usar uma mistura de TABs e espaços para o recuo. Cada nível de recuo irá ter um tamanho de <option
>largura-recuo</option
>, enquanto os restantes níveis de recuo serão otimizados para usar tantos caracteres TAB quantos possíveis.</para>
<para
>Quando for executado, este comando irá ativar o recuo com espaços e, se a largura de recuo não estiver definida, corresponderá a metade da <option
>largura-tabulação</option
> do documento, no momento da execução.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-word-wrap</command
><arg choice="req"
>BOOLEANO ativar</arg
></cmdsynopsis
></term>
<listitem
><para
>Ativa a quebra de linha dinâmica, de acordo com o parâmetro <userinput
>ativar</userinput
></para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-replace-tabs-save</command
><arg choice="req"
>BOOLEANO ativar</arg
></cmdsynopsis
></term>
<listitem
><para
>Quando estiver ativo, as tabulações serão substituídas por espaços em branco, sempre que o documento for salvo.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-remove-trailing-space-save</command
><arg choice="req"
>BOOLEANO ativar</arg
></cmdsynopsis
></term>
<listitem
><para
>Quando estiver ativo, os espaços finais serão removidos de cada linha, sempre que o documento for salvo.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-indent-mode</command
><arg choice="req"
>TEXTO nome</arg
></cmdsynopsis
></term>
<listitem
><para
>Configura o modo de recuo automático como <userinput
>nome</userinput
>. Se o <userinput
>nome</userinput
> não for conhecido, o modo é configurado como 'none' (nenhum). Os modos válidos são 'none', 'normal', 'cstyle', 'haskell', 'lilypond', 'lisp', 'python', 'ruby' e 'xml'.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-auto-ident</command
><arg choice="req"
>BOOLEANO script</arg
></cmdsynopsis
></term>
<listitem
><para
>Ativa ou desativa o recuo automático.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-highlight</command
><arg choice="req"
>TEXTO realce</arg
></cmdsynopsis
></term>
<listitem
><para
>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 <menuchoice
><guimenu
>Ferramentas</guimenu
><guisubmenu
>Realce</guisubmenu
></menuchoice
>. Este comando oferece uma lista de completação automática para o seu argumento.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>reload-scripts</command
></cmdsynopsis
></term>
<listitem
><para
>Recarrega todos os <link linkend="advanced-editing-tools-scripting"
>scripts do JavaScript</link
> usados pelo Kate, incluindo scripts de indentação e de linha de comando.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-mode</command
><arg choice="req"
>STRING modo</arg
></cmdsynopsis
></term>
<listitem
><para
>Seleciona o esquema de tipo de arquivo para o documento atual. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>nn[oremap]</command
><arg choice="req"
>TEXTO original</arg
> <arg choice="req"
>TEXTO mapeado</arg
></cmdsynopsis
></term>
<listitem
><para
>Mapeia a sequência <userinput
>original</userinput
> para a <userinput
>mapeada</userinput
>.</para
></listitem>
</varlistentry>

</variablelist>

</sect3>

<sect3 id="advanced-editing-tools-commandline-commands-edit">
<title
>Comandos de edição</title>

<para
>Estes comandos modificam o documento atual.</para>

<variablelist>
<varlistentry>
<term
><cmdsynopsis
><command
>indent</command
></cmdsynopsis
></term>
<listitem
><para
>Recua as linhas selecionadas ou a linha atual.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>unindent</command
></cmdsynopsis
></term>
<listitem
><para
>Remove um nível de recuo das linhas selecionadas ou da linha atual.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>cleanindent</command
></cmdsynopsis
></term>
<listitem
><para
>Limpa o recuo das linhas selecionadas ou da linha atual, de acordo com a configuração de recuo no documento. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>comment</command
></cmdsynopsis
></term>
<listitem
><para
>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.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>uncomment</command
></cmdsynopsis
></term>
<listitem
><para
>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.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>kill-line</command
></cmdsynopsis
></term>
<listitem
><para
>Remove a linha atual.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>replace</command
><arg choice="req"
>TEXTO padrão</arg
><arg choice="req"
>TEXTO substituição</arg
></cmdsynopsis
></term>
<listitem
><para
>Substitui o texto correspondente ao <userinput
>padrão</userinput
> por <userinput
>substituição</userinput
>. Se você quiser incluir espaços em branco no <userinput
>padrão</userinput
>, deverá colocar tanto o <userinput
>padrão</userinput
> como a <userinput
>substituição</userinput
> entre aspas simples ou duplas. Se os argumentos não estiverem entre estes caracteres, a primeira palavra é usada como <userinput
>padrão</userinput
> e o resto como a <userinput
>substituição</userinput
>. Se a <userinput
>substituição</userinput
> estiver em branco, cada ocorrência do <userinput
>padrão</userinput
> será removida.</para>
<para
>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 <userinput
>replace:opções padrão substituição</userinput
>. As opções disponíveis são: <variablelist>

<varlistentry>
<term
><userinput
>b</userinput
></term>
<listitem
><para
>Pesquisar para trás.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>c</userinput
></term>
<listitem
><para
>Procura a partir da posição do cursor.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>e</userinput
></term>
<listitem
><para
>Procura apenas na área selecionada.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>r</userinput
></term>
<listitem
><para
>Faz uma pesquisa por uma determinada expressão regular. Se estiver ativo, você poderá usar o <userinput
>\N</userinput
>, onde o N é um número que representa as capturas no texto de substituição.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>s</userinput
></term>
<listitem
><para
>Faz uma pesquisa com distinção entre maiúsculas e minúsculas.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>p</userinput
></term>
<listitem
><para
>Pede permissão para substituir a próxima ocorrência.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>w</userinput
></term>
<listitem
><para
>Faz uma correspondência apenas com palavras inteiras.</para
></listitem>
</varlistentry>

</variablelist>

</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>date</command
><arg choice="req"
>TEXTO formato</arg
></cmdsynopsis
></term>
<listitem
><para
>Insere um texto de data/hora, tal como está definido pelo <userinput
>formato</userinput
> indicado, ou com o formato <quote
>aaaa-MM-dd hh:mm:ss</quote
>, se não for indicada qualquer formatação. As traduções a seguir são feitas quando for interpretado o <userinput
>formato</userinput
>: <informaltable
> <tgroup cols="2"
> <tbody>
<row
><entry
><literal
>d</literal
></entry
><entry
>O dia, como um número sem um zero inicial (1-31).</entry
></row>
<row
><entry
><literal
>dd</literal
></entry
><entry
>O dia, como um número com um zero inicial (01-31).</entry
></row>
<row
><entry
><literal
>ddd</literal
></entry
><entry
>O nome do dia abreviado, no formato regional (p.ex. 'Seg'..'Dom').</entry
></row>
<row
><entry
><literal
>dddd</literal
></entry
><entry
>O nome do dia completo, no formato regional (p.ex. 'Segunda'..'Domingo').</entry
></row>
<row
><entry
><literal
>M</literal
></entry
><entry
>O mês, como um número sem um zero inicial (1-12).</entry
></row>
<row
><entry
><literal
>MM</literal
></entry
><entry
>O mês, como um número com um zero inicial (01-12).</entry
></row>
<row
><entry
><literal
>MMMM</literal
></entry
><entry
>O nome completo do mês localizado (ex.: 'Janeiro'..'Dezembro').</entry
></row>
<row
><entry
><literal
>MMM</literal
></entry
><entry
>O nome do mês abreviado, no formato regional (p.ex. 'Jan'..'Dez').</entry
></row>
<row
><entry
><literal
>aa</literal
></entry
><entry
>O ano, como um número de dois algarismos (00-99).</entry
></row>
<row
><entry
><literal
>aaaa</literal
></entry
><entry
>O ano, como um número de quatro algarismos (1752-8000).</entry
></row>
<row
><entry
><literal
>h</literal
></entry
><entry
>As horas sem um zero inicial (0..23 ou 1..12 no caso do formato AM/PM).</entry
></row>
<row
><entry
><literal
>hh</literal
></entry
><entry
>As horas com um zero inicial (00..23 ou 01..12 no caso do formato AM/PM).</entry
></row>
<row
><entry
><literal
>m</literal
></entry
><entry
>Os minutos sem um zero inicial (0..59).</entry
></row>
<row
><entry
><literal
>mm</literal
></entry
><entry
>Os minutos com um zero inicial (00..59).</entry
></row>
<row
><entry
><literal
>s</literal
></entry
><entry
>Os segundos sem um zero inicial (0..59).</entry
></row>
<row
><entry
><literal
>ss</literal
></entry
><entry
>Os minutos com um zero inicial (00..59).</entry
></row>
<row
><entry
><literal
>z</literal
></entry
><entry
>Os milissegundos sem um zero inicial (0..999).</entry
></row>
<row
><entry
><literal
>zzz</literal
></entry
><entry
>Os milissegundos com zeros iniciais (000..999).</entry
></row>
<row
><entry
><literal
>AP</literal
></entry
><entry
>Usar o formato de horas AM/PM. O AP será substituído por "AM" ou por "PM".</entry
></row>
<row
><entry
><literal
>ap</literal
></entry
><entry
>Usar o formato de horas am/pm. O ap será substituído por "am" ou por "pm".</entry
></row>
</tbody>
</tgroup>
</informaltable>

</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>char</command
><arg choice="req"
>TEXTO identificador</arg
></cmdsynopsis
></term>
<listitem>
<para
>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 <userinput
>char: [número]</userinput
> na caixa de entrada e clique em <guibutton
>OK</guibutton
>.</para>

<example>
<title
>exemplos do comando <command
>char</command
></title>

<para
>Entrada: <userinput
>char:234</userinput
></para>
<para
>Resultado: <computeroutput
>&#234;</computeroutput
></para>
<para
>Entrada: <userinput
>char:0x1234</userinput
></para>
<para
>Resultado: <computeroutput
>&#x1234;</computeroutput
></para>
</example>

</listitem>
</varlistentry>

<varlistentry>
<term>
<indexterm
><primary
>substituir no estilo sed</primary>
<secondary
>procurar no estilo sed</secondary
></indexterm>
<command
>s///[ig]</command
> <command
>%s///[ig]</command
></term>

<listitem>
<para
>Este comando faz um sed como operação de procura/substituição na linha atual, ou em um arquivo inteiro (<command
>%s///</command
>).</para>

<para
>Em resumo, é procurado o texto que combine com o <emphasis
>padrão de busca </emphasis
>, 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 <emphasis
>referências anteriores</emphasis
>, isto é, o comando lembra qual parte procurada combinou no parênteses; estas strings podem ser reutilizadas no padrão de substituição, referidas como <userinput
>\1</userinput
> para o primeiro conjunto de parênteses, <userinput
>\2</userinput
> para o segundo e assim por diante.</para>

<para
>Para procurar por um caractere literal <literal
>(</literal
> ou <literal
>)</literal
>, você precisa usar o caractere de <emphasis
>escape</emphasis
>, que é o caractere de barra invertida: <userinput
>\(\)</userinput
></para>

<para
>Se você puser um <userinput
>i</userinput
> 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 <userinput
>g</userinput
> no fim, todas as ocorrências do padrão serão substituídas, caso contrário, só será substituída a primeira ocorrência.</para>

<example>

<title
>Substituindo texto na linha atual</title>

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

<para
>&quot;Droga!&quot; você pensa, é claro que é <classname
>MinhaClasse</classname
>. 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 <userinput
>s/minhaclasse/MinhaClasse/i</userinput
>, clica no botão <guibutton
>OK</guibutton
>, salva o arquivo e compila &ndash; com sucesso, sem erros.</para>

</example>

<example>
<title
>Substituindo texto no arquivo inteiro</title>

<para
>Imagine que você tem um arquivo, no qual está mencionada a string <quote
>Senhorita Jensen</quote
> várias vezes, quando aparece alguém e lhe diz que ela casou com o <quote
>Senhor Jones</quote
>. Você quer, é claro, substituir todas as ocorrências de <quote
>Senhorita Jensen</quote
> por <quote
>Senhora Jones</quote
>.</para>

<para
>Entre na linha de comando e digite o comando <userinput
>%s/Srª Silva/Srª Braga/</userinput
>, pressionando RETURN para terminar.</para>

</example>

<example>
<title
>Um Exemplo Mais Avançado</title>

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

<para
>Suponha que você possui a seguinte linha: <programlisting
>void MinhaClasse::DoStringOps( String      &amp;foo, String &amp;bar, String *p, int  &amp;a, int &amp;b )</programlisting>
</para>
<para
>Agora, você pode perceber que este não é um código bom, e decidir que deseja usar a palavra-chave <constant
>const</constant
> para todos os argumentos <quote
>address of</quote
>, aqueles caracterizados pelo operador &amp; 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.</para>

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

<para
>Saída <computeroutput
>void MinhaClasse::DoStringOps( const String &amp;foo, const String &amp;bar, String *p, const int &amp;a, const int &amp;b )</computeroutput
></para>

<para
>Missão completa! Agora, o que aconteceu? Bem, procuramos por espaços em branco (<literal
>\s+</literal
>) seguidos por um ou mais caracteres alfabéticos(<literal
>\w+</literal
>) seguidos por mais espaços em branco (<literal
>\s+</literal
>) 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 <quote
>const</quote
>, seguido por um espaço em branco, seguido por nosso pedaço alfabético (<literal
>\1</literal
>) seguido por um espaço em branco, em por fim, seguido por nosso E comercial salvo (<literal
>\2</literal
>)</para>

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

</example>

</listitem>

</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>sort</command
></cmdsynopsis
></term>
<listitem
><para
>Ordena o texto selecionado ou todo o documento.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>natsort</command
></cmdsynopsis
></term>
<listitem
><para
>Ordena as linhas selecionadas ou todo o documento naturalmente.</para>

<example>
<title
><command
>sort</command
> x <command
>natsort</command
></title>
<para
><userinput
>sort(a10, a1, a2)</userinput
> resulta em <computeroutput
>a1, a10, a2</computeroutput
></para>
<para
><command
>natsort(a10, a1, a2)</command
> resulta em <computeroutput
>a1, a2, a10</computeroutput
></para>
</example
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>moveLinesDown</command
></cmdsynopsis
></term>
<listitem
><para
>Move as linhas selecionadas para baixo.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>moveLinesUp</command
></cmdsynopsis
></term>
<listitem
><para
>Move as linhas selecionadas para cima.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>uniq</command
></cmdsynopsis
></term>
<listitem
><para
>Remove linhas duplicadas do texto selecionado ou do documento inteiro.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>rtrim</command
></cmdsynopsis
></term>
<listitem
><para
>Remove o espaço à direita do texto selecionado ou do documento inteiro.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>ltrim</command
></cmdsynopsis
></term>
<listitem
><para
>Remove o espaço à esquerda do texto selecionado ou do documento inteiro.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>join</command
><arg choice="opt"
>TEXTO separador</arg
></cmdsynopsis
></term>
<listitem
><para
>Mescla as linhas selecionadas ou o documento inteiro. Opcionalmente, recebe um parâmetro definindo um separador, por exemplo: <userinput
><command
>join</command
> ', '</userinput
> </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>rmblank</command
></cmdsynopsis
></term>
<listitem
><para
>Remove todos os espaços em branco do texto selecionado ou do documento inteiro.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>unwrap</command
></cmdsynopsis
></term>
<listitem
><para
>Remove as quebras de linha do texto selecionado ou do documento inteiro.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>each</command
><arg choice="req"
>TEXTO script</arg
></cmdsynopsis
></term>
<listitem
><para
>Fornecida uma função do JavaScript como argumento, chama pela lista de linhas selecionadas e substitui-as com o valor de retorno desta chamada.</para>

<example>
<title
>Mescla as linhas selecionadas</title>
<para
><userinput
><command
>each</command
> 'function(lines){return lines.join(", ")}' </userinput
></para>

<para
>Ou, de maneira resumida:</para>
<para
><userinput
><command
>each</command
> 'lines.join(", ")'</userinput
></para>
</example>

</listitem>
</varlistentry>



<varlistentry>
<term
><cmdsynopsis
><command
>filter</command
><arg choice="req"
>TEXTO script</arg
></cmdsynopsis
></term>
<listitem
><para
>Fornecida uma função do JavaScript como argumento, chama pela lista de linhas selecionadas e remove-as onde a chamada retorna falso.</para>

<example>
<title
>Remover linhas em branco</title>
<para
><userinput
><command
>filter</command
> 'function(1){return 1.length 
> 0;}' </userinput
></para>

<para
>Ou, de maneira resumida:</para>
<para
><userinput
><command
>filter</command
> 'line.length 
> 0'</userinput
></para>
</example>

</listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>map</command
><arg choice="req"
>TEXTO script</arg
></cmdsynopsis
></term>
<listitem
><para
>Fornecida uma função do JavaScript como argumento, chama pela lista de linhas selecionadas e substitui a linha com o valor de retorno da chamada.</para>

<example>
<title
>Remover linhas em branco</title>
<para
><userinput
><command
>map</command
> 'function(line){return line.replace(/^s+/,"");}' </userinput
></para>

<para
>Ou, de maneira resumida:</para>
<para
><userinput
><command
>map</command
> 'line.replace(/^s+/,"")'</userinput
></para>
</example>

</listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>duplicateLinesUp</command
></cmdsynopsis
></term>
<listitem
><para
>Duplica as linhas selecionadas acima da seleção atual.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>duplicateLinesDown</command
></cmdsynopsis
></term>
<listitem
><para
>Duplica as linhas selecionadas abaixo da seleção atual.</para>
</listitem>
</varlistentry>

</variablelist>

</sect3>

<sect3 id="advanced-editing-tools-commandline-commands-navigation">
<title
>Comandos de navegação</title>

<variablelist>

<varlistentry>
<term
><cmdsynopsis
><command
>goto</command
><arg choice="req"
>INT linha</arg
></cmdsynopsis
></term>
<listitem
><para
>Este comando vai para a linha indicada.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>grep</command
> <arg choice="req"
>TEXTO padrão</arg
> </cmdsynopsis
></term>
<listitem
><para
>Pesquisa o documento pela expressão regular <userinput
>padrão</userinput
>. Para mais informações, veja as <xref linkend="regular-expressions"/></para>
</listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>find</command
><arg choice="req"
>TEXTO padrão</arg
></cmdsynopsis
></term>
<listitem
><para
>Este comando vai para a primeira ocorrência do <userinput
>padrão</userinput
>, de acordo com a configuração. As ocorrências a seguir poderão ser encontradas com a opção <menuchoice
><guimenu
>Editar</guimenu
><guimenuitem
>Procurar Próximo</guimenuitem
></menuchoice
> (o atalho por padrão é o <keycap
>F3</keycap
>).</para>
<para
>O comando de procura poderá ser configurado adicionando dois-pontos, seguidos de uma ou mais opções, sendo o formato <userinput
>find:opções padrão</userinput
>. São suportadas as seguintes opções:</para>

<variablelist>

<varlistentry>
<term
><userinput
>b</userinput
></term>
<listitem
><para
>Pesquisar para trás.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>c</userinput
></term>
<listitem
><para
>Procura a partir da posição do cursor.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>e</userinput
></term>
<listitem
><para
>Procura apenas na área selecionada.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>r</userinput
></term>
<listitem
><para
>Faz uma pesquisa por uma determinada expressão regular. Se estiver ativo, você poderá usar o <userinput
>\N</userinput
>, onde o N é um número que representa as capturas no texto de substituição.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>s</userinput
></term>
<listitem
><para
>Faz uma pesquisa com distinção entre maiúsculas e minúsculas.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>w</userinput
></term>
<listitem
><para
>Faz uma correspondência apenas com palavras inteiras.</para
></listitem>
</varlistentry>

</variablelist>
</listitem>

</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>ifind</command
><arg choice="req"
>TEXTO padrão</arg
></cmdsynopsis
></term>
<listitem
><para
>Este comando oferece uma procura <quote
>à-medida-que-digita</quote
>. Você poderá configurar o comportamento da procura adicionando dois-pontos (:), seguidos de uma ou mais opções, como se segue: <userinput
>ifind:opções padrão</userinput
>. As opções permitidas são <variablelist>
<varlistentry>
<term
><userinput
>b</userinput
></term>
<listitem
><para
>Pesquisar para trás.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>r</userinput
></term>
<listitem
><para
>Faz uma procura por uma expressão regular.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>s</userinput
></term>
<listitem
><para
>Faz uma pesquisa com distinção entre maiúsculas e minúsculas.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>c</userinput
></term>
<listitem
><para
>Procura a partir da posição do cursor.</para
></listitem>
</varlistentry>

</variablelist>
</para
></listitem>
</varlistentry>

</variablelist>

</sect3>


<sect3 id="advanced-editing-tools-commandline-commands-basic">
<title
>Comandos das funções básicas do editor (dependem do aplicativo em que o componente de edição é usado)</title>

<variablelist>

<varlistentry>
<term
><cmdsynopsis
><command
>w</command
></cmdsynopsis
></term>
<listitem
><para
>Salvar o documento atual.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>wa</command
></cmdsynopsis
></term>
<listitem
><para
>Salvar todos os documentos abertos.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>q</command
></cmdsynopsis
></term>
<listitem
><para
>Fechar o documento atual.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>qa</command
></cmdsynopsis
></term>
<listitem
><para
>Fechar todos os documentos abertos.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>wq</command
></cmdsynopsis
></term>
<listitem
><para
>Salvar e fechar o documento atual.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>wqa</command
></cmdsynopsis
></term>
<listitem
><para
>Salvar e fechar todos os documentos abertos.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>x</command
></cmdsynopsis
></term>
<listitem
><para
>Salvar e fechar o documento atual somente se ele foi modificado. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>x</command
></cmdsynopsis
></term>
<listitem
><para
>Salvar e fechar todos os documentos abertos somente se eles foram modificados.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>bp</command
></cmdsynopsis
></term>
<listitem
><para
>Ir para o documento anterior na lista de documentos. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>bn</command
></cmdsynopsis
></term>
<listitem
><para
>Ir para o próximo documento na lista de documentos. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>new</command
></cmdsynopsis
></term>
<listitem
><para
>Abrir um novo documento em uma divisão de visão horizontal. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>vnew</command
></cmdsynopsis
></term>
<listitem
><para
>Abrir um novo documento em uma divisão de visão vertical. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>e</command
></cmdsynopsis
></term>
<listitem
><para
>Recarregar o documento atual se ele tiver sido modificado em disco. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>enew</command
></cmdsynopsis
></term>
<listitem
><para
>Editar um novo documento. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>print</command
></cmdsynopsis
></term>
<listitem
><para
>Abrir a janela de impressão para imprimir o documento atual. </para
></listitem>
</varlistentry>

</variablelist>

</sect3>


</sect2>

</sect1>

<sect1 id="advanced-editing-tools-code-folding">
<title
>Usando o Desdobramento de Código</title>

<para
>O desdobramento ou dobragem de código permite-lhe ocultar partes de um documento no editor, tornando mais simples analisar globalmente arquivos grandes. No &kappname;, 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 <userinput
>BEGIN</userinput
> e <userinput
>END</userinput
>.</para>

<para
>Para usar a funcionalidade de desdobramento de código, ative os marcadores com a opção <menuchoice
><guimenu
>Exibir</guimenu
><guimenuitem
>Mostrar as Marcações de Dobragem</guimenuitem
></menuchoice
>, 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 triangulares para indicar a operação possível numa determinada região: um triângulo para baixo significa que a região é expandida; clicar sobre ele irá recolher a região, clicar em um triângulo para direita irá expandi-la.</para>

<para
>Estão disponíveis onze comandos para manipular o estado das regiões dobradas; para tal, veja a <link linkend="view-code-folding"
>documentação do menu</link
>. </para>

<para
>As linhas recolhidas serão lembradas quando um arquivo é fechado, assim quando você reabri-lo, os nós que estiverem recolhidos permanecerão dobrados. Isto se aplica a operações de recarregamento também.</para>

<para
>Se você não quiser usar a funcionalidade de desdobramento do código, poderá desativar a opção <guilabel
>Mostrar as marcações de dobragem (se disponíveis)</guilabel
> na página <link linkend="appearance"
>Aparência</link
> do editor de configuração.</para>

</sect1>

<sect1 id="advanced-editing-tools-scripting">
<title
>Estender o &kappname; com Programas</title>

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

<sect2 id="advanced-editing-tools-scripting-indentation">
<title
>Scripts de recuo</title>

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

<para
>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 <filename
>*.js</filename
>, chamado por exemplo <filename
>javascript.js</filename
> na pasta pessoal local <filename
>$KDEHOME/share/apps/katepart/script/indentation</filename
>. </para>

<sect3 id="advanced-editing-tools-scripting-indentation-header">
<title
>O cabeçalho do script de recuo</title>
<para
>O cabeçalho do arquivo <filename
>javascript.js</filename
> está incorporado num comentário e possui o seguinte formato <programlisting>
/* kate-script
 * name: JavaScript
 * author: Nome de Exemplo &lt;nome.exemplo@endereco.org&gt;
 * license: BSD
 * revision: 1
 * kate-version: 3.4
 * required-syntax-style: javascript
 * indent-languages: javascript
 * priority: 0
 * i18n-catalog: meucatalogo
 *
 * 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.
 */
</programlisting
> Cada item será agora explicado em detalhe: <itemizedlist>
<listitem
><para
><literal
>kate-script</literal
> [obrigatório]: Este texto tem que aparecer na primeira linha do arquivo <filename
>*.js</filename
>, caso contrário, o &kappname; irá ignorar o script. </para
></listitem>
<listitem
><para
><literal
>name</literal
> [obrigatório]: Este é o nome do modo de recuo que aparece no menu <menuchoice
><guimenu
>Ferramentas</guimenu
><guimenuitem
>Recuar</guimenuitem
></menuchoice
> e na janela de configuração. </para
></listitem>
<listitem
><para
><literal
>author</literal
> [opcional]: O nome e a informação de contato do autor. </para
></listitem>
<listitem
><para
><literal
>license</literal
> [opcional]: Forma curta da licença, como por exemplo BSD ou LGPLv3. </para
></listitem>
<listitem
><para
><literal
>revision</literal
> [obrigatório]: A versão do programa. Este número deverá ser aumentado sempre que o programa for modificado. </para
></listitem>
<listitem
><para
><literal
>kate-version</literal
> [obrigatório]: A versão mínima do &kappname; necessária. </para
></listitem>
<listitem
><para
><literal
>required-syntax-style</literal
> [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 <quote
>comportamento inesperado</quote
> causado pelo uso do recuador sem o esquema de realce esperado. Por exemplo, o recuado do Ruby faz uso dos arquivos <filename
>ruby.js</filename
> e <filename
>ruby.xml</filename
>. </para
></listitem>
<listitem
><para
><literal
>indent-languages</literal
> [opcional]: Uma lista, separada por vírgulas, de estilos de sintaxe que este módulo consegue recuar corretamente, p.ex.: c++, java. </para
></listitem>
<listitem
><para
><literal
>priority</literal
> [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. </para
></listitem>
<listitem
><para
><literal
>i18n-catalog</literal
> [opcional]: Catálogo de mensagens adicional (arquivo <literal
>.po</literal
>) carregado para a tradução de endentações de terceiros.</para
></listitem>
</itemizedlist>
</para>

<para
>O &kappname; lê todos os pares no formato <quote
><replaceable
>chave</replaceable
>:<replaceable
>valor</replaceable
></quote
> 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. </para>

</sect3>

<sect3 id="advanced-editing-tools-scripting-indentation-body">
<title
>O código-fonte do recuador</title>
<para
>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: <programlisting>
// 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 <menuchoice
><guimenu
>Ferramentas</guimenu
><guimenuitem
>Alinhar</guimenuitem
></menuchoice>
    // a variável 'caractere' está em branco, i.e. caractere == ''.
    //
    // ver também: API de Programação
    return -2;
}
</programlisting
> A função <function
>indent()</function
> tem três parâmetros: <itemizedlist
> <listitem
><para
><literal
>linha</literal
>: a linha que tem de ser recuada</para
></listitem
> <listitem
><para
><literal
>larguraRecuo</literal
>: o número de espaços correspondentes a cada recuo</para
></listitem
> <listitem
><para
><literal
>caractere</literal
>: ou um caractere de mudança de linha (<literal
>ch == '\n'</literal
>), algum dos caracteres de ativação indicados em <literal
>caracteresAtivacao</literal
> ou vazio, caso o usuário tenha invocado a ação <menuchoice
><guimenu
>Ferramentas</guimenu
><guimenuitem
>Alinhar</guimenuitem
></menuchoice
>.</para
></listitem
> </itemizedlist
> O valor devolvido pela função <function
>indent()</function
> define como a linha será recuada. Se o valor devolvido for um número inteiro, é interpretado da seguinte forma: <itemizedlist
> <listitem
><para
>valor devolvido <literal
>-2</literal
>: não fazer nada</para
></listitem
> <listitem
><para
>valor devolvido <literal
>-1</literal
>: mantém o recuo (procura pela linha não-vazia anterior)</para
></listitem
> <listitem
><para
>valor devolvido <literal
> 0</literal
>: números &gt;= 0 definem a largura do recuo em espaços</para
></listitem
> </itemizedlist
> Em alternativa, poderá ser devolvida uma lista com dois elementos: <itemizedlist
> <listitem
><para
><literal
>return [ recuo, alinhamento ];</literal
></para
></listitem
> </itemizedlist
> 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 <quote
>alinhamento</quote
>. 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 <quote
>modo misto</quote
>. </para>

<para
>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 &lt;tab&gt; representa uma tabulação e o '.' representa um espaço: <programlisting>
1: &lt;tab&gt;&lt;tab&gt;xpto("olá",
2: &lt;tab&gt;&lt;tab&gt;......."mundo");
</programlisting
> Ao recuar a linha 2, a função <function
>indent()</function
> 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. </para>

<para
>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 <filename
>$KDEDIR/share/apps/katepart/script/indentation</filename
>. </para>

<para
>A criação de um módulo de recuo necessita o recarregamento dos 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 comando e invocar o comando <command
>reload-scripts</command
>. </para>

<para
>Se você criar programas úteis, por favor considere a hipótese de contribuir com eles para o Projeto do &kappname;, <ulink url="mailto:kwrite-devel@kde.org"
>contactando para isso a lista de correio</ulink
>. </para>

</sect3>
</sect2>

<sect2 id="advanced-editing-tools-scripting-command-line">
<title
>Programas da Linha de Comando</title>

<para
>Como é difícil satisfazer as necessidades de todos, o &kappname; suporta algumas ferramentas auxiliares para manipular rapidamente o texto, usando para isso a <link linkend="advanced-editing-tools-commandline"
>linha de comando incorporada</link
>. Por exemplo, o comando <command
>sort</command
> está implementado como um programa. Esta seção explica como criar arquivos <filename
>*.js</filename
> que estendem o &kappname; com algumas funções auxiliares arbitrárias. </para>

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

<sect3 id="advanced-editing-tools-scripting-command-line-header">
<title
>O Cabeçalho do Programa da Linha de Comando</title>
<para
>O cabeçalho de cada programa da linha de comandos está incorporado como um comentário e encontra-se no seguinte formato <programlisting>
/* kate-script
 * author: Nome de Exemplo &lt;nome.exemplo@endereco.org&gt;
 * license: BSD
 * revision: 1
 * kate-version: 3.4
 * functions: sort, format-paragraph
 * i18n-catalog: meucatalogo
 *
 * Uma linha sem o símbolo ':' interrompe o processamento do cabeçalho. Isto é, você poderá adicionar
 * algum texto opcional aqui como, por exemplo, uma licença detalhada.
 */
</programlisting
> Cada um dos elementos será explicado em detalhe: <itemizedlist>
<listitem
><para
><literal
>kate-script</literal
> [obrigatório]: Este texto tem que aparecer na primeira linha do arquivo <filename
>*.js</filename
>, caso contrário, o &kappname; irá ignorar o script.</para
></listitem>
<listitem
><para
><literal
>author</literal
> [opcional]: O nome e a informação de contato do autor.</para
></listitem>
<listitem
><para
><literal
>license</literal
> [opcional]: Forma curta da licença, como por exemplo BSD ou LGPLv3.</para
></listitem>
<listitem
><para
><literal
>revision</literal
> [obrigatório]: A versão do programa. Este número deverá ser aumentado sempre que o programa for modificado.</para
></listitem>
<listitem
><para
><literal
>kate-version</literal
> [obrigatório]: A versão mínima do &kappname; necessária.</para
></listitem>
<listitem
><para
><literal
>functions</literal
> [obrigatório]: Uma lista, separada por vírgulas, dos comandos do programa.</para
></listitem>
<listitem
><para
><literal
>i18n-catalog</literal
> [opcional]: Catálogo de mensagens adicional (arquivo <literal
>.po</literal
>) carregado para a tradução dos programas de terceiros.</para
></listitem>
</itemizedlist>
</para>

<para
>O &kappname; lê todos os pares no formato <quote
><replaceable
>chave</replaceable
>:<replaceable
>valor</replaceable
></quote
>, 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 <link linkend="advanced-editing-tools-commandline"
>linha de comando incorporada</link
>. </para>
</sect3>

<sect3 id="advanced-editing-tools-scripting-command-line-body">
<title
>O Código-Fonte do Programa</title>

<para
>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 <command
>ordenar</command
> e <command
>formatar-paragrafo</command
>. Todas as funções têm a seguinte sintaxe: <programlisting
>// bibliotecas necessárias do katepart js, p.ex., range.js se você usar Range
function &lt;nome&gt;(arg1, arg2, ...)
{
    // ... implementação, ver também: API de Programação
}
</programlisting>
</para>

<para
>Os argumentos na linha de comando são passados à função como <parameter
>arg1</parameter
>, <parameter
>arg2</parameter
>, etc. Para poder indicar a documentação de cada comando, basta implementar a função '<function
>help</function
>', como demonstrado a seguir: <programlisting>
function help(cmd)
{
    if (cmd == "sort") {
        return i18n("Ordena o texto selecionado.");
    } else if (cmd == "...") {
        // ...
    }
}
</programlisting
> Executar <command
>help sort</command
> na linha de comando, irá invocar esta função de ajuda com o argumento <parameter
>cmd</parameter
> igual ao comando indicado, i.e. <parameter
>cmd == "sort"</parameter
>. O &kappname; irá assim apresentar o texto devolvido como documentação ao usuário. Certifique-se de <link linkend="advanced-editing-tools-scripting-api-i18n"
>traduzir os textos</link
>. </para>

<sect4 id="advanced-editing-tools-scripting-command-line-shortcuts">
<title
>Associar combinações de teclas</title>
<para
>Para poder atribuir atalhos de teclado, o programa terá que fornecer uma função chamada <literal
>action</literal
> da seguinte forma: <programlisting>
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;
}
</programlisting
> O parâmetro <literal
>comando</literal
> 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: <itemizedlist>
<listitem
><para
><literal
>a.text</literal
> [obrigatório]: O texto que aparece no menu <menuchoice
><guimenu
>Ferramentas</guimenu
> <guisubmenu
>Programas</guisubmenu
> </menuchoice
>. Certifique-se de usar o <literal
>i18n</literal
> para as traduções.</para
></listitem>
<listitem
><para
><literal
>a.icon</literal
> [opcional]: O ícone aparece após ao texto no menu. Todos os nomes de ícones do KDE poderão ser usados aqui.</para
></listitem>
<listitem
><para
><literal
>a.category</literal
> [opcional]: Se for indicada uma categoria, o programa aparece num submenu. Certifique-se de usar o <literal
>i18n</literal
> para as traduções.</para
></listitem>
<listitem
><para
><literal
>a.interactive</literal
> [opcional]: Se o programa precisa de interação por parte do usuário, configure este valor como <literal
>true</literal
> (verdadeiro).</para
></listitem>
<listitem
><para
><literal
>a.shortcut</literal
> [opcional]: A combinação de teclas indicada aqui é o atalho de teclado padrão. Por exemplo: Ctrl+Alt+T. Veja a <ulink url="http://doc.qt.nokia.com/latest/qt.html#Key-enum"
>documentação do Qt</ulink
> para mais detalhes.</para
></listitem>
</itemizedlist>
</para>


<para
>Criar um programa para a linha de comando requer o recarregamento dos programas, de modo a ver se as alterações funcionam apropriadamente. Em vez de reiniciar a aplicação, basta mudar para a linha de comando e invocar o comando <command
>reload-scripts</command
>. </para>

<para
>Se você criar programas úteis, por favor considere a hipótese de contribuir com eles para o Projeto do &kappname;, <ulink url="mailto:kwrite-devel@kde.org"
>contactando para isso a lista de correio</ulink
>. </para>

</sect4>
</sect3>
</sect2>

<sect2 id="advanced-editing-tools-scripting-api">
<title
>API de Programação</title>

<para
>A API de programação aqui apresentada está disponível em todos os scripts, p.ex., os scripts de indentação e os comandos do terminal. O <classname
>Cursor</classname
> e o <classname
>Range</classname
> são fornecidos por arquivos de bibliotecas no <filename
>$KDEDIR/share/apps/katepart/libraries</filename
>. Elas serão necessárias, caso queira usar algumas das funções <classname
>Document</classname
> ou <classname
>View</classname
> no seu script. Inclua a biblioteca necessária usando: <programlisting
>// bibliotecas necessárias do katepart js, p.ex., range.js se você usar Range
require ("range.js");
</programlisting>
</para>

<para
>Para ampliar a API padrão de scripts com funções e protótipos próprios, basta criar um arquivo novo na pasta de configuração local do KDE, em <filename
>$KDEHOME/share/apps/katepart/libraries</filename
> e incluí-lo no seu script usando: <programlisting
>require ("myscriptnamehere.js");
</programlisting>

</para>

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

<sect3 id="advanced-editing-tools-scripting-api-prototypes">
<title
>Cursores e Intervalos</title>

<para
>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 <literal
>(linha, coluna)</literal
> 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. </para>

<sect4 id="advanced-editing-tools-scripting-api-cursors">
<title
>O Protótipo do Cursor</title>

<variablelist
><varlistentry>
<term
><synopsis
>Cursor();
</synopsis
></term>
<listitem
><para
>Construtor. Devolve um Cursor na posição <literal
>(0, 0)</literal
>.</para>
<para
>Exemplo: <function
>var cursor = new Cursor();</function
> </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Cursor(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Construtor. Devolve um Cursor na posição (linha, coluna). </para>
<para
>Exemplo: <function
>var cursor = new Cursor(3, 42);</function
> </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Cursor(<parameter
>Cursor <replaceable
>outro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Construtor de cópia. Devolve uma cópia do cursor <replaceable
>outro</replaceable
>. </para>
<para
>Exemplo: <function
>var copia = new Cursor(outro);</function
> </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Cursor Cursor.clone();
</synopsis
></term>
<listitem
><para
>Devolve uma cópia do cursor.</para>
<para
>Exemplo: <function
>var clone = cursor.clone();</function
> </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Cursor.isValid();
</synopsis
></term>
<listitem
><para
>Verifica se o cursor é válido. O cursor é inválido no caso em que a linha e/ou coluna sejam iguais a <literal
>-1</literal
>. </para>
<para
>Exemplo: <function
>var valido = cursor.isValid();</function
> </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Cursor Cursor.invalid();
</synopsis
></term>
<listitem
><para
>Devolve um novo cursor inválido, localizado em <literal
>(-1, -1)</literal
>. </para>
<para
>Exemplo: <function
>var cursorInvalido = cursor.invalid();</function
> </para
></listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>int Cursor.compareTo(<parameter
>Cursor <replaceable
>outro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Compara este cursor com o cursor <replaceable
>outro</replaceable
>. Devolve <itemizedlist>
<listitem
><para
><literal
>-1</literal
>, se este cursor for localizado antes do cursor <replaceable
>outro</replaceable
>,</para
></listitem>
<listitem
><para
><literal
>0</literal
>, se ambos os cursores forem iguais e</para
></listitem>
<listitem
><para
><literal
>+1</literal
>, se este cursor se localizar após o cursor <replaceable
>outro</replaceable
>.</para
></listitem>
</itemizedlist>
</para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Cursor.equals(<parameter
>Cursor <replaceable
>outro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se este o cursor e o <replaceable
>outro</replaceable
> forem iguais, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String Cursor.toString();
</synopsis
></term>
<listitem
><para
>Devolve o cursor como um texto no formato <quote
><literal
>Cursor(linha, coluna)</literal
></quote
>. </para
></listitem>
</varlistentry
></variablelist>

</sect4>


<sect4 id="advanced-editing-tools-scripting-api-ranges">
<title
>O Protótipo do Intervalo</title>

<variablelist
><varlistentry>
<term
><synopsis
>Range();
</synopsis
></term>
<listitem
><para
>Construtor. A invocação de <literal
>new Range()</literal
> devolve um intervalo Range de (0, 0) - (0, 0). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Range(<parameter
>Cursor <replaceable
>inicio</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>fim</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Construtor. A invocação de <literal
>new Range(<replaceable
>início</replaceable
>, <replaceable
>fim</replaceable
>)</literal
> devolve o intervalo (<replaceable
>início</replaceable
>, <replaceable
>fim</replaceable
>). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Range(<parameter
>int <replaceable
>linhaInicial</replaceable
></parameter
>, <parameter
>int <replaceable
>colunaInicial</replaceable
></parameter
>, <parameter
>int <replaceable
>linhaFinal</replaceable
></parameter
>, <parameter
>int <replaceable
>colunaFinal</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Construtor. A invocação de <literal
>new Range(<replaceable
>linhaInicial</replaceable
>, <replaceable
>colunaInicial</replaceable
>, <replaceable
>linhaFinal</replaceable
>, <replaceable
>colunaFinal</replaceable
>)</literal
> devolve um intervalo Range de (<replaceable
>linhaInicial</replaceable
>, <replaceable
>colunaInicial</replaceable
>) até (<replaceable
>linhaFinal</replaceable
>, <replaceable
>colunaFinal</replaceable
>). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Range(<parameter
>Range <replaceable
>outro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Construtor de cópia. Devolve uma cópia do intervalo Range <replaceable
>outro</replaceable
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Range Range.clone();
</synopsis
></term>
<listitem
><para
>Devolve uma cópia do intervalo. </para>
<para
>Exemplo: <function
>var clone = intervalo.clone();</function
> </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.isValid();
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se tanto o cursor de início como o de fim forem válidos, caso contrário devolve <literal
>false</literal
> (falso). </para>
<para
>Exemplo: <function
>var valido = intervalo.isValid();</function
> </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.invalid();
</synopsis
></term>
<listitem
><para
>Devolve o intervalo Range de (-1, -1) até (-1, -1). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.contains(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se este intervalo contiver a posição do cursor, caso contrário devolve <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.contains(<parameter
>Range <replaceable
>outro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se este intervalo contiver o intervalo Range <replaceable
>outro</replaceable
>, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.containsColumn(<parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se a <replaceable
>coluna</replaceable
> estiver no intervalo semi-aberto <literal
>[início.coluna, fim.coluna)</literal
>, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.containsLine(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se a <replaceable
>linha</replaceable
> estiver no intervalo semi-aberto <literal
>[início.linha, fim.linha)</literal
>, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.overlaps(<parameter
>Range <replaceable
>outro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se este intervalo e o intervalo <replaceable
>outro</replaceable
> compartilharem uma região em comum, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.overlapsLine(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se a <replaceable
>linha</replaceable
> estiver no intervalo <literal
>[início.linha, fim.linha]</literal
>, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.overlapsColumn(<parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se a <replaceable
>coluna</replaceable
> estiver no intervalo <literal
>[início.coluna, fim.coluna]</literal
>, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.onSingleLine();
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se o intervalo inicia e termina na mesma linha, p.ex. se <replaceable
>Range.start.line == Range.end.line</replaceable
>. </para>
<para
>Desde: KDE 4.9 </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.equals(<parameter
>Range <replaceable
>outro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se este intervalo e o intervalo <replaceable
>outro</replaceable
> forem iguais, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String Range.toString();
</synopsis
></term>
<listitem
><para
>Devolve o intervalo como um texto no formato <quote
><literal
>Range(Cursor(linha, coluna), Cursor(linha, coluna))</literal
></quote
>. </para
></listitem>
</varlistentry
></variablelist>

</sect4>
</sect3>

<sect3 id="advanced-editing-tools-scripting-api-global">
<title
>Funções Globais</title>
<para
>Esta seção apresenta todas as funções globais.</para>


<sect4 id="advanced-editing-tools-scripting-api-includes">
<title
>Arquivos de leitura e inclusão</title>

<variablelist
><varlistentry>
<term
><synopsis
>String read(<parameter
>String <replaceable
>arquivo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Irá procurar pelo <replaceable
>arquivo</replaceable
> indicado em relação à pasta <literal
>katepart/script/files</literal
> e irá devolver o seu conteúdo como texto. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void require(<parameter
>String <replaceable
>Arquivo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Irá procurar pelo <replaceable
>arquivo</replaceable
> indicado em relação à pasta <literal
>katepart/script/libraries</literal
> e avaliá-lo. O <literal
>require</literal
> está protegido internamente contra inclusões múltiplas do mesmo <replaceable
>arquivos</replaceable
>. </para
></listitem>
</varlistentry
></variablelist>

</sect4>

<sect4 id="advanced-editing-tools-scripting-api-debug">
<title
>Depuração</title>

<variablelist
><varlistentry>
<term
><synopsis
>void debug(<parameter
>String <replaceable
>texto</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Imprime o <replaceable
>texto</replaceable
> no <literal
>stdout</literal
>, mais precisamente no console que lança a aplicação. </para
></listitem>
</varlistentry
></variablelist>

</sect4>

<sect4 id="advanced-editing-tools-scripting-api-i18n">
<title
>Tradução</title>

<para
>Para um suporte regional completo, existem diversas funções para traduzir os textos nos programas, nomeadamente o <literal
>i18n</literal
>, o <literal
>i18nc</literal
>, o <literal
>i18np</literal
> e o <literal
>i18ncp</literal
>. Estas funções comportam-se exatamente como as <ulink url="http://techbase.kde.org/Development/Tutorials/Localization/i18n"
> funções de tradução do KDE</ulink
>. </para>

<para
>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. 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 <literal
>i18n-catalog</literal
>. </para>

<variablelist
><varlistentry>
<term
><synopsis
>void i18n(<parameter
>String <replaceable
>texto</replaceable
></parameter
>, <replaceable
>arg1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Traduz o <replaceable
>texto</replaceable
> na língua usada pela aplicação. Os argumentos <replaceable
>arg1</replaceable
>, ..., são opcionais e usados para substituir os itens <literal
>%1</literal
>, <literal
>%2</literal
>, etc.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>void i18nc(<parameter
>String <replaceable
>contexto</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>, <replaceable
>arg1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Traduz o <replaceable
>texto</replaceable
> na língua usada pela aplicação. Além disso, o texto do <replaceable
>contexto</replaceable
> fica visível aos tradutores para que possam dar uma tradução mais adequada. Os argumentos <replaceable
>arg1</replaceable
>, ..., são opcionais e são usados para substituir os itens de substituição <literal
>%1</literal
>, <literal
>%2</literal
>, etc.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>void i18np(<parameter
>String <replaceable
>singular</replaceable
></parameter
>, <parameter
>String <replaceable
>plural</replaceable
></parameter
>, <parameter
>int <replaceable
>número</replaceable
></parameter
>, <replaceable
>arg1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Traduz tanto o texto <replaceable
>singular</replaceable
> como o <replaceable
>plural</replaceable
> para a língua usada pela aplicação, dependendo do <replaceable
>número</replaceable
> indicado. Os argumentos <replaceable
>arg1</replaceable
>, ..., são opcionais e usados para substituir os itens de substituição <literal
>%1</literal
>, <literal
>%2</literal
>, etc.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>void i18ncp(<parameter
>String <replaceable
>contexto</replaceable
></parameter
>, <parameter
>String <replaceable
>singular</replaceable
></parameter
>, <parameter
>String <replaceable
>plural</replaceable
></parameter
>, <parameter
>int<replaceable
>número</replaceable
></parameter
>, <replaceable
>arg1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Traduz tanto o texto <replaceable
>singular</replaceable
> como o <replaceable
>plural</replaceable
> para a língua usada pela aplicação, dependendo do <replaceable
>número</replaceable
> indicado. Adicionalmente, o texto do <replaceable
>contexto</replaceable
> é visível para as tradutores, para que possam fornecer uma tradução mais adequada. Os argumentos <replaceable
>arg1</replaceable
>, ..., são opcionais e são usados para substituir os itens <literal
>%1</literal
>, <literal
>%2</literal
>, etc.</para
></listitem>
</varlistentry
></variablelist>

</sect4>
</sect3>

<sect3 id="advanced-editing-tools-scripting-api-view">
<title
>A API do View</title>
<para
>Sempre que um programa está sendo executado, existe uma variável global <quote
><literal
>view</literal
></quote
> que representa a área de edição ativa no momento. Segue-se uma lista com todas as funções disponíveis para o View. <variablelist
><varlistentry>
<term
><synopsis
><function
>Cursor view.cursorPosition()</function
>
</synopsis
></term>
<listitem
><para
>Devolve a posição atual do cursor na janela.</para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void view.setCursorPosition(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
void view.setCursorPosition(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Altera a posição atual do cursor para uma (linha, coluna) qualquer ou para o cursor indicado. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Cursor view.virtualCursorPosition();
</synopsis
></term>
<listitem
><para
>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. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void view.setVirtualCursorPosition(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
void view.setVirtualCursorPosition(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Altera a posição atual do cursor virtual para uma (linha, coluna) qualquer ou para o cursor indicado. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String view.selectedText();
</synopsis
></term>
<listitem
><para
>Devolve o texto selecionado. Se não tiver nenhum texto selecionado, o texto devolvido vem vazio. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool view.hasSelection();
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se a janela contiver algum texto selecionado, caso contrário devolve <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Range view.selection();
</synopsis
></term>
<listitem
><para
>Devolve o intervalo de texto selecionado. O intervalo devolvido é inválido, caso não esteja selecionado nenhum texto. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void view.setSelection(<parameter
>Range <replaceable
>intervalo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Altera o texto selecionado para o intervalo indicado. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void view.removeSelectedText();
</synopsis
></term>
<listitem
><para
>Remove o texto selecionado. Se a janela não tiver nenhuma seleção feita, isto não faz nada. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void view.selectAll();
</synopsis
></term>
<listitem
><para
>Seleciona todo o texto no documento. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void view.clearSelection();
</synopsis
></term>
<listitem
><para
>Limpa a seleção de texto atual, sem remover o texto. </para
></listitem>
</varlistentry
></variablelist>
</para>
</sect3>

<sect3 id="advanced-editing-tools-scripting-api-document">
<title
>A API do Document</title>
<para
>Sempre que está sendo executado um programa, existe uma variável global <quote
><literal
>document</literal
></quote
> que representa o documento ativo no momento. Segue-se uma lista com todas as funções disponíveis para o Document. <variablelist
><varlistentry>
<term
><synopsis
>String document.fileName();
</synopsis
></term>
<listitem
><para
>Devolve o nome do arquivo do documento, ou então um texto vazio para as janelas de texto ainda por salvar. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.url();
</synopsis
></term>
<listitem
><para
>Devolve o URL completo do documento, ou então um texto vazio para as janelas de texto ainda por salvar. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.mimeType();
</synopsis
></term>
<listitem
><para
>Devolve o tipo MIME do documento, ou então o tipo <literal
>application/octet-stream</literal
> se não for encontrado qualquer tipo MIME apropriado. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.encoding();
</synopsis
></term>
<listitem
><para
>Devolve a codificação usada atualmente para salvar o arquivo. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>String document.highlightingMode();
</synopsis
></term>
<listitem
><para
>Devolve o modo de realce global usado para todo o documento. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>String document.highlightingModeAt(<parameter
>Cursor <replaceable
>pos</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o modo de realce usado na posição do cursor indicada do documento. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>Array document.embeddedHighlightingModes();
</synopsis
></term>
<listitem
><para
>Devolve uma lista com os modos de realce incorporados neste documento. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>bool document.isModified();
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se o documento tiver alguma alteração por salvar, caso contrário devolve <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.text();
</synopsis
></term>
<listitem
><para
>Devolve o conteúdo inteiro do documento numa única sequência de texto. As mudanças de linha estão marcadas com o caracter de mudança de linha <quote
><literal
>\n</literal
></quote
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.text(<parameter
>int <replaceable
>daLinha</replaceable
></parameter
>, <parameter
>int <replaceable
>daColuna</replaceable
></parameter
>, <parameter
>int <replaceable
>paraLinha</replaceable
></parameter
>, <parameter
>int <replaceable
>paraColuna</replaceable
></parameter
>);
String document.text(<parameter
>Cursor <replaceable
>de</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>para</replaceable
></parameter
>);
String document.text(<parameter
>Range <replaceable
>intervalo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>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. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.line(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>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. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.wordAt(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
String document.wordAt(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve a palavra na posição do cursor indicada. </para
></listitem>
</varlistentry>


<varlistentry>
<term>
<synopsis
>Range document.wordRangeAt(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
Range document.wordRangeAt(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis>
</term>
<listitem
><para
>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. </para>
<para
>Desde: KDE 4.9 </para>
</listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.charAt(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
String document.charAt(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o caracter na posição do cursor indicada. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.firstChar(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o primeiro caracter da <replaceable
>linha</replaceable
> indicada que não seja um espaço em branco. O primeiro caracter encontra-se na coluna 0. Se a linha estiver em branco ou só tiver espaços em branco, o texto devolvido vem vazio. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.lastChar(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o último caracter da <replaceable
>linha</replaceable
> indicada que não seja um espaço em branco. O primeiro caracter encontra-se na coluna 0. Se a linha estiver em branco ou só tiver espaços em branco, o texto devolvido vem vazio. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isSpace(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
bool document.isSpace(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se o caracter na posição indicada do cursor for um espaço em branco, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.matchesAt(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>);
bool document.matchesAt(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se o <replaceable
>texto</replaceable
> indicado corresponder à posição indicada do cursor, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.startsWith(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>, <parameter
>bool <replaceable
>ignorarEspacos</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se a linha começar por <replaceable
>texto</replaceable
>, caso contrário devolve <literal
>false</literal
> (falso). O argumento <replaceable
>ignorarEspacos</replaceable
> controla se os espaços envolventes são ignorados ou não. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.endsWith(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>, <parameter
>bool <replaceable
>ignorarEspacos</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), caso a linha termine em <replaceable
>texto</replaceable
>, caso contrário devolve <literal
>false</literal
> (falso). O argumento <replaceable
>ignorarEspacos</replaceable
> controla se os espaços envolventes são ignorados. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.setText(<parameter
>String <replaceable
>texto</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Altera o texto do documento por inteiro. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.clear();
</synopsis
></term>
<listitem
><para
>Limpa o texto no documento por inteiro. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.truncate(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
bool document.truncate(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Trunca a linha indicada, na coluna ou posição do cursor indicadas. Devolve <literal
>true</literal
> (verdadeiro) em caso de sucesso ou <literal
>false</literal
> (falso) se a linha não estiver dentro do intervalo do documento. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.insertText(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>);
bool document.insertText(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Insere o <replaceable
>texto</replaceable
> na posição do cursor indicada. Devolve <literal
>true</literal
>, em caso de sucesso, ou <literal
>false</literal
> (falso), se o documento estiver apenas para leitura. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.removeText(<parameter
>int <replaceable
>daLinha</replaceable
></parameter
>, <parameter
>int <replaceable
>daColuna</replaceable
></parameter
>, <parameter
>int <replaceable
>paraLinha</replaceable
></parameter
>, <parameter
>int <replaceable
>paraColuna</replaceable
></parameter
>);
bool document.removeText(<parameter
>Cursor <replaceable
>de</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>para</replaceable
></parameter
>);
bool document.removeText(<parameter
>Range <replaceable
>intervalo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Remove o texto no intervalo indicado. Devolve <literal
>true</literal
> (verdadeiro), em caso de sucesso, ou <literal
>false</literal
> (falso), se o documento estiver no modo apenas para leitura. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.insertLine(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Insere o texto na linha indicada. Devolve <literal
>true</literal
> (verdadeiro), em caso de sucesso, ou <literal
>false</literal
> (falso), caso o documento esteja apenas para leitura ou se a linha não estiver no intervalo do documento. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.removeLine(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Remove a linha de texto indicada. Devolve <literal
>true</literal
> (verdadeiro), em caso de sucesso, ou <literal
>false</literal
> (falso), caso o documento esteja no modo apenas para leitura ou se a linha não estiver no intervalo do documento. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.wrapLine(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
bool document.wrapLine(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Reparte a linha na posição indicada pelo cursor. Devolve <literal
>true</literal
> (verdadeiro) em caso de sucesso ou <literal
>false</literal
> (falso) se, p.ex., a linha &lt; 0. </para>
<para
>Desde: KDE 4.9 </para>
</listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void document.joinLines(<parameter
>int <replaceable
>linhaInicial</replaceable
></parameter
>, <parameter
>int <replaceable
>linhaFinal</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Junta as linhas de <replaceable
>linhaInicial</replaceable
> até <replaceable
>linhaFinal</replaceable
>. Duas linhas de texto sucessivas estão sempre separadas por um espaço em branco. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.lines();
</synopsis
></term>
<listitem
><para
>Devolve o número de linhas do documento. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.length();
</synopsis
></term>
<listitem
><para
>Devolve o número de caracteres do documento. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.lineLength(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o comprimento da <replaceable
>linha</replaceable
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void document.editBegin();
</synopsis
></term>
<listitem
><para
>Inicia um grupo de edição para agrupar operações a desfazer/refazer. Certifique-se de invocar sempre o <function
>editEnd()</function
> tantas vezes quanto invoca o <function
>editBegin()</function
>. A invocação do <function
>editBegin()</function
> usa um contador de referências interno, i.e., esta chamada pode ser encadeada. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void document.editEnd();
</synopsis
></term>
<listitem
><para
>Termina um grupo de edição. A última invocação do <function
>editEnd()</function
> (i.e., a correspondente à primeira chamada do <function
>editBegin()</function
>) termina o passo de edição. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.firstColumn(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve a primeira coluna não em branco para a <replaceable
>linha</replaceable
> indicada. Se só existirem espaços em branco na linha, o valor devolvido é <literal
>-1</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.lastColumn(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve a última coluna que não esteja em branco para a <replaceable
>linha</replaceable
> indicada. Se só existirem espaços em branco na linha, o valor devolvido é <literal
>-1</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.prevNonSpaceColumn(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
int document.prevNonSpaceColumn(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve a coluna com caracteres não-brancos que começa na posição de cursor indicada e pesquisa para trás. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.nextNonSpaceColumn(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
int document.nextNonSpaceColumn(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve a coluna com caracteres não-brancos que começa na posição de cursor indicada e pesquisa para a frente. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.prevNonEmptyLine(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve a primeira linha não-vazia que contém caracteres não-nulos, pesquisando depois para trás. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.nextNonEmptyLine(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve a primeira linha não-vazia que contém caracteres não-nulos, pesquisando depois para a frente. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isInWord(<parameter
>String <replaceable
>caracter</replaceable
></parameter
>, <parameter
>int <replaceable
>atributo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), caso o <replaceable
>caractere</replaceable
> e <replaceable
>atributo</replaceable
> indicados possam fazer parte de uma palavra, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.canBreakAt(<parameter
>String <replaceable
>caracter</replaceable
></parameter
>, <parameter
>int <replaceable
>atributo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se o <replaceable
>caracter</replaceable
> indicado com o <replaceable
>atributo</replaceable
> indicado for adequado para mudar de linha, caso contrário devolve <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.canComment(<parameter
>int <replaceable
>atributoInicial</replaceable
></parameter
>, <parameter
>int <replaceable
>atributoFinal</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (falso), caso um intervalo que começa e termina com os atributos indicados possa ser comentado; caso contrário, devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.commentMarker(<parameter
>int <replaceable
>atributo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o marcador de comentários, usado em linhas únicas, para um determinado <replaceable
>atributo</replaceable
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.commentStart(<parameter
>int <replaceable
>atributo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o marcador de início de comentários, usado em linhas múltiplas, para um determinado <replaceable
>atributo</replaceable
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.commentEnd(<parameter
>int <replaceable
>atributo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o marcador de fim de comentários, usado em linhas múltiplas, para um determinado <replaceable
>atributo</replaceable
>. </para
></listitem>
</varlistentry>



<varlistentry>
<term
><synopsis
>int document.attribute(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
int document.attribute(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o atributo na posição do cursor indicada. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isAttribute(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>, <parameter
>int <replaceable
>atributo</replaceable
></parameter
>);
bool document.isAttribute(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>int <replaceable
>atributo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se o atributo na posição do cursor indicada for igual a <replaceable
>atributo</replaceable
>, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.attributeName(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
String document.attributeName(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o nome do atributo como um texto legível. Isto é igual ao nome <literal
>itemData</literal
> dos arquivos de realce de sintaxe. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isAttributeName(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>, <parameter
>String <replaceable
>nome</replaceable
></parameter
>);
bool document.isAttributeName(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>String <replaceable
>nome</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se o nome do atributo, numa dada posição do cursor, corresponder ao <replaceable
>nome</replaceable
> indicado, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.variable(<parameter
>String <replaceable
>chave</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o valor da variável do documento identificada pela <replaceable
>chave</replaceable
>. Se a variável do documento não existir, o valor devolvido é um texto em branco. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.setVariable(<parameter
>String <replaceable
>chave</replaceable
></parameter
>, <parameter
>String <replaceable
>valor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Define o valor da variável do documento solicitada pela <replaceable
>chave</replaceable
>. Devolve o valor da variável alterada. </para>
<para
>Veja também: <link linkend="config-variables"
>Variáveis de documento do Kate</link
> </para>
<para
>Desde: KDE 4.8 </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.firstVirtualColumn(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve a coluna virtual do primeiro caracter não-nulo na linha indicada, ou então <literal
>-1</literal
> se a linha estiver em branco ou só tiver caracteres de espaços em branco. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.lastVirtualColumn(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve a coluna virtual do último caracter não-nulo na linha indicada, ou então <literal
>-1</literal
> se a linha estiver em branco ou só tiver caracteres de espaços em branco. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.toVirtualColumn(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
int document.toVirtualColumn(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
Cursor document.toVirtualCursor(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Converte a posição do cursor <quote
>real</quote
> para uma posição virtual, retornando um int ou um objeto Cursor. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.fromVirtualColumn(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>colunaVirtual</replaceable
></parameter
>);
int document.fromVirtualColumn(<parameter
>Cursor <replaceable
>cursorVirtual</replaceable
></parameter
>);
Cursor document.fromVirtualCursor(<parameter
>Cursor <replaceable
>cursorVirtual</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Converte a posição virtual do cursor para uma posição do cursor <quote
>real</quote
>, retornando um int ou um objeto Cursor. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Cursor document.anchor(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>, <parameter
>Char <replaceable
>caracter</replaceable
></parameter
>);
Cursor document.anchor(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>Char <replaceable
>caracter</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Pesquisa para trás pelo caracter indicado, começando na posição do cursor indicada. Por exemplo, se for passado o '(', como caracter, esta função irá devolver a posição do '(' de abertura. Isto implica uma contagem das referências, i.e., os outros '(...)' são ignorados. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Cursor document.rfind(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>, <parameter
>int <replaceable
>atributo</replaceable
> = -1</parameter
>);
Cursor document.rfind(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>, <parameter
>int <replaceable
>atributo</replaceable
> = -1</parameter
>);
</synopsis
></term>
<listitem
><para
>Pesquisa para trás pelo texto indicado, com o <replaceable
>atributo</replaceable
> apropriado. O argumento <replaceable
>atributo</replaceable
> é ignorado se for igual a <literal
>-1</literal
>. O cursor devolvido é inválido, caso o texto não tenha sido encontrado. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.defStyleNum(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
int document.defStyleNum(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o estilo padrão que é usado na posição do cursor indicada. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isCode(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
bool document.isCode(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se o atributo na posição do cursor indicada não for igual a todos os seguintes estilos: <literal
>dsComment</literal
>, <literal
>dsString</literal
>, <literal
>dsRegionMarker</literal
>, <literal
>dsChar</literal
>, <literal
>dsOthers</literal
>. </para
></listitem>
</varlistentry>



<varlistentry>
<term
><synopsis
>bool document.isComment(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
bool document.isComment(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> se o atributo do caracter na posição do cursor for <literal
>dsComment</literal
>; caso contrário devolve <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isString(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
bool document.isString(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se o atributo do caracter na posição do cursor for <literal
>dsString</literal
>, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isRegionMarker(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
bool document.isRegionMarker(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se o atributo do caracter na posição do cursor for <literal
>dsRegionMarker</literal
>, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isChar(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
bool document.isChar(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se o atributo do caracter na posição do cursor for <literal
>dsChar</literal
>, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isOthers(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
bool document.isOthers(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se o atributo do caracter na posição do cursor for <literal
>dsOthers</literal
>, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry
></variablelist>
</para>

</sect3>
</sect2>
</sect1>
</chapter>
