<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
>José</firstname
><surname
>Pires</surname
><affiliation
><address
><email
>zepires@gmail.com</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 à selecção ou à linha actual, se não estiver texto seleccionado. Os comentários são suportados pelo formato do texto que você está a editar.</para>

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

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

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

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

<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 a sequência de teclado relacionada, que por omissã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 omissão é o <keycombo action="simul"
>&Ctrl;&Shift;<keycap
>D</keycap
></keycombo
>.</para>

</sect1>

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

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

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

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

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

<sect2 id="advanced-editing-tools-commandline-commands">
<title
>Comandos Normais da Linha de Comandos</title>

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

<varlistentry>
<term
>BOOLEANO</term>
<listitem
><para
>Isto é usado com os comandos que activam ou desactivam 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
>Um texto separado por plicas (') ou aspas (") quando tiver 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 activos. Isto poderá ser útil se quiser usar uma configuração diferente da predefinida como, por exemplo, na indentação. </para>

<variablelist>

<varlistentry>
<term
><cmdsynopsis
><command
>set-tab-width</command
><arg choice="req"
>INTEGER 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"
>INTEGER largura</arg
></cmdsynopsis
></term>
<listitem
><para
>Configura a largura da indentação como <userinput
>largura</userinput
>. Só é usado se o utilizador indentar com espaços.</para
></listitem>
</varlistentry>

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

<varlistentry>
<term
><cmdsynopsis
><command
>set-icon-border</command
><arg choice="req"
>BOOLEAN activar</arg
> </cmdsynopsis
></term>
<listitem
><para
>Configura a visibilidade do contorno dos ícones.</para
></listitem>
</varlistentry>

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

<varlistentry>
<term
><cmdsynopsis
><command
>set-line-numbers</command
><arg choice="req"
>BOOLEAN activar</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"
>BOOLEAN activar</arg
></cmdsynopsis
></term>
<listitem
><para
>Se estiver activo, as tabulações são substituídas por espaços, à medida que você vai escrevendo. </para
></listitem>
</varlistentry>

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

<varlistentry>
<term
><cmdsynopsis
><command
>set-show-tabs</command
><arg choice="req"
>BOOLEAN activar</arg
></cmdsynopsis
></term>
<listitem
><para
>Se estiver activo, 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"
>BOOLEAN activar</arg
></cmdsynopsis
></term>
<listitem
><para
>Se estiver activo, a indentação será visualizada como uma linha pontilhada vertical.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-indent-spaces</command
><arg choice="req"
>BOOLEAN activar</arg
></cmdsynopsis
></term>
<listitem
><para
>Se estiver activo, o editor irá indentar com <option
>largura-indentação</option
> espaços por cada nível de indentação, em vez de usar o carácter TAB.</para
></listitem>
</varlistentry>

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

<varlistentry>
<term
><cmdsynopsis
><command
>set-word-wrap</command
><arg choice="req"
>BOOLEAN activar</arg
></cmdsynopsis
></term>
<listitem
><para
>Activa a mudança de linha dinâmica, de acordo com o parâmetro <userinput
>activar</userinput
></para
></listitem>
</varlistentry>

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

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

<varlistentry>
<term
><cmdsynopsis
><command
>set-indent-mode</command
><arg choice="req"
>STRING nome</arg
></cmdsynopsis
></term>
<listitem
><para
>Configura o modo de indentação automática 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 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"
>BOOLEAN programa</arg
></cmdsynopsis
></term>
<listitem
><para
>Activa ou desactiva a indentação automática.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-highlight</command
><arg choice="req"
>STRING 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
>Volta a carregar todos os <link linkend="advanced-editing-tools-scripting"
>programas em JavaScript</link
> usados pelo Kate, incluindo os módulos de indentação e programas da linha de comandos.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-mode</command
><arg choice="req"
>STRING modo</arg
></cmdsynopsis
></term>
<listitem
><para
>Escolhe o esquema do tipo de ficheiro do documento actual. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>nn[oremap]</command
><arg choice="req"
>STRING original</arg
> <arg choice="req"
>STRING associado</arg
></cmdsynopsis
></term>
<listitem
><para
>Associa a sequência de teclas <userinput
>original</userinput
> a <userinput
>associado</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 actual.</para>

<variablelist>
<varlistentry>
<term
><cmdsynopsis
><command
>indent</command
></cmdsynopsis
></term>
<listitem
><para
>Indenta as linhas seleccionadas ou a linha actual.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>unindent</command
></cmdsynopsis
></term>
<listitem
><para
>Remove um nível de indentação das linhas seleccionadas ou da linha actual.</para
></listitem>
</varlistentry>

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

<varlistentry>
<term
><cmdsynopsis
><command
>comment</command
></cmdsynopsis
></term>
<listitem
><para
>Insere marcações de comentários para fazer da selecção, linhas seleccionadas ou da linha actual um comentário, de acordo com o formato de texto definido pela definição do realce de sintaxe para o documento.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>uncomment</command
></cmdsynopsis
></term>
<listitem
><para
>Remove os marcadores de comentários da selecção, linhas seleccionadas ou da linha actual, de acordo com o formato de texto definido pela definição do realce de sintaxe do documento.</para
></listitem>
</varlistentry>

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

<varlistentry>
<term
><cmdsynopsis
><command
>replace</command
><arg choice="req"
> STRING padrão</arg
> <arg choice="req"
>STRING 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 plicas ou aspas. 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
>Procura 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 seleccionada.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>r</userinput
></term>
<listitem
><para
>Faz uma pesquisa por uma dada expressão regular. Se estiver activo, 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ões 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"
>STRING 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 seguintes 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 do mês por extenso, no formato regional (p.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 milisegundos sem um zero inicial (0..999).</entry
></row>
<row
><entry
><literal
>zzz</literal
></entry
><entry
>Os milisegundos 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"
>STRING identificador</arg
></cmdsynopsis
></term>
<listitem>
<para
>Este comando permite-lhe introduzir caracteres literais pelo seu identificador numérico em decimal, octal ou hexadecimal. Para o usar, invoque a Janela do Comando de Edição e escreva <userinput
>char: [number]</userinput
> no campo de texto, carregando depois em <guibutton
>OK</guibutton
>.</para>

<example>
<title
>Exemplos do <command
>char</command
></title>

<para
>Introdução: <userinput
>char:234</userinput
></para>
<para
>Resultado: <computeroutput
>&#234;</computeroutput
></para>
<para
>Introdução: <userinput
>char:0x1234</userinput
></para>
<para
>Resultado: <computeroutput
>&#x1234;</computeroutput
></para>
</example>

</listitem>
</varlistentry>

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

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

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

<para
>Para procurar por um <literal
>(</literal
> ou <literal
>)</literal
>, é necessário <emphasis
>escapá-lo</emphasis
>, usando uma barra invertida: <userinput
>\(\)</userinput
></para>

<para
>Se 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
>Substituir texto na linha actual</title>

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

<para
>&quot;Bolas!&quot; pensa você, é óbvio que é <classname
>MyClass</classname
>. Vá à linha 3902 e, em vez de tentar procurar a palavra no texto, invoque a Janela de Comando de Edição, escreva <userinput
>s/myclass/MyClass/i</userinput
>, carregue no botão <guibutton
>OK</guibutton
>, grave o ficheiro e compile &ndash; com sucesso, sem o erro.</para>

</example>

<example>
<title
>Substituir texto no ficheiro inteiro</title>

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

<para
>Entre na linha de comandos e escreva no campo de texto o comando <userinput
>%s/Srª Silva/Srª Pires/</userinput
>, carregando em 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 em baixo).</para>

<para
>Imagine que tem a seguinte linha: <programlisting
>void MinhaClass::OperacaoTexto( String      &amp;xpto, String &amp;xpto2 String *p, int  &amp;a, int &amp;b )</programlisting>
</para>
<para
>Agora, chega à conclusão que este não é um código bonito, e decide que quer usar a palavra <constant
>const</constant
> para todos os <quote
>endereços dos argumentos</quote
>, os quais se caracterizam pelo operador &amp; à frente do nome do argumento. Também irá querer simplificar os espaços em branco, de modo a que haja apenas um espaço entre cada palavra.</para>

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

<para
>Resultado: <computeroutput
>void MinhaClasse::OperacaoTexto( const String &amp;xpto, const String &amp;xpto2 String *p, const int &amp;a, const int &amp;b )</computeroutput
></para>

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

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

</example>

</listitem>

</varlistentry>

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

<varlistentry>
<term
><cmdsynopsis
><command
>natsort</command
></cmdsynopsis
></term>
<listitem
><para
>Ordena naturalmente o texto seleccionado ou o documento inteiro.</para>

<example>
<title
><command
>sort</command
> vs. <command
>natsort</command
></title>
<para
>O <userinput
>sort(a10, a1, a2)</userinput
> devolverá <computeroutput
>a1, a10, a2</computeroutput
></para>
<para
>O <command
>natsort(a10, a1, a2)</command
> devolverá <computeroutput
>a1, a2, a10</computeroutput
></para>
</example
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>moveLinesDown</command
></cmdsynopsis
></term>
<listitem
><para
>Desce as linhas seleccionadas.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>moveLinesUp</command
></cmdsynopsis
></term>
<listitem
><para
>Sobe as linhas seleccionadas.</para
></listitem>
</varlistentry>

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

<varlistentry>
<term
><cmdsynopsis
><command
>rtrim</command
></cmdsynopsis
></term>
<listitem
><para
>Remove os espaços finais do texto seleccionado ou do documento inteiro.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>ltrim</command
></cmdsynopsis
></term>
<listitem
><para
>Remove os espaços iniciais do texto seleccionado ou do documento inteiro.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>join</command
><arg choice="opt"
>STRING separador</arg
></cmdsynopsis
></term>
<listitem
><para
>Junta as linhas seleccionadas ou o documento inteiro. Opcionalmente, recebe um parâmetro que define um separador, como 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 seleccionado ou do documento inteiro.</para
></listitem>
</varlistentry>

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

<varlistentry>
<term
><cmdsynopsis
><command
>each</command
><arg choice="req"
>STRING programa</arg
></cmdsynopsis
></term>
<listitem
><para
>Dada uma função em JavaScript como argumento, invoca-a para a lista de linhas seleccionadas e substitui-as pelo valor devolvido por essa chamada.</para>

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

<para
>Ou, de forma mais resumida:</para>
<para
><userinput
><command
>each</command
> 'linhas.join(", ")'</userinput
></para>
</example>

</listitem>
</varlistentry>



<varlistentry>
<term
><cmdsynopsis
><command
>filter</command
><arg choice="req"
>STRING programa</arg
></cmdsynopsis
></term>
<listitem
><para
>Dada uma função em JavaScript como argumento, invoca-a para a lista de linhas seleccionadas e remove as que devolvam um valor falso para essa chamada.</para>

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

<para
>Ou, de forma mais resumida:</para>
<para
><userinput
><command
>filter</command
> 'linha.length 
> 0'</userinput
></para>
</example>

</listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>map</command
><arg choice="req"
>STRING programa</arg
></cmdsynopsis
></term>
<listitem
><para
>Dada uma função em JavaScript como argumento, invoca-a para a lista de linhas seleccionadas e substitui a linha pelo valor da chamada.</para>

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

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

</listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>duplicateLinesUp</command
></cmdsynopsis
></term>
<listitem
><para
>Duplica as linhas seleccionadas acima da selecção actual.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>duplicateLinesDown</command
></cmdsynopsis
></term>
<listitem
><para
>Duplica as linhas seleccionadas abaixo da selecção actual.</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"
>STRING padrão</arg
> </cmdsynopsis
></term>
<listitem
><para
>Procura no 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"
>STRING 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 seguintes poderão ser encontradas com a opção <menuchoice
><guimenu
>Editar</guimenu
><guimenuitem
>Procurar o Seguinte</guimenuitem
></menuchoice
> (o atalho por omissão é o <keycap
>F3</keycap
>).</para>
<para
>O comando de procura poderá ser configurado se adicionar 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
>Procura 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 seleccionada.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>r</userinput
></term>
<listitem
><para
>Faz uma pesquisa por uma dada expressão regular. Se estiver activo, 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"
>STRING padrão</arg
></cmdsynopsis
></term>
<listitem
><para
>Este comando oferece uma procura <quote
>à-medida-que-escreve</quote
>. Você poderá configurar o comportamento da procura se adicionar 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
>Procura 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 de Edição (Estas dependem da aplicação em que o componente de edição é usado)</title>

<variablelist>

<varlistentry>
<term
><cmdsynopsis
><command
>w</command
></cmdsynopsis
></term>
<listitem
><para
>Grava o documento actual.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>wa</command
></cmdsynopsis
></term>
<listitem
><para
>Grava todos os documentos abertos de momento.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>q</command
></cmdsynopsis
></term>
<listitem
><para
>Fecha o documento actual.</para
></listitem>
</varlistentry>

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

<varlistentry>
<term
><cmdsynopsis
><command
>wq</command
></cmdsynopsis
></term>
<listitem
><para
>Grava e fecha o documento actual.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>wqa</command
></cmdsynopsis
></term>
<listitem
><para
>Grava e fecha todos os documentos abertos de momento.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>x</command
></cmdsynopsis
></term>
<listitem
><para
>Grava e fecha o documento actual, somente se tiver sido alterado. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>x</command
></cmdsynopsis
></term>
<listitem
><para
>Grava e fecha todos os documentos abertos de momento, somente se tiverem sido alterados.</para
></listitem>
</varlistentry>

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

<varlistentry>
<term
><cmdsynopsis
><command
>bn</command
></cmdsynopsis
></term>
<listitem
><para
>Vai para o documento seguinte na lista de documentos. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>new</command
></cmdsynopsis
></term>
<listitem
><para
>Abre um documento numa janela dividida horizontalmente. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>vnew</command
></cmdsynopsis
></term>
<listitem
><para
>Abre um documento numa janela dividida verticalmente. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>e</command
></cmdsynopsis
></term>
<listitem
><para
>Volta a carregar o documento actual, caso tenha sido alterado no disco. </para
></listitem>
</varlistentry>

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

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

</variablelist>

</sect3>


</sect2>

</sect1>

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

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

<para
>Para usar a funcionalidade de desdobramento de código, active os marcadores com a opção <menuchoice
><guimenu
>Ver</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 do ecrã, mostra uma vista gráfica sobre as regiões que poderão ser recolhidas ou expandidas, com símbolos de triângulos para indicar a operação possível numa dada região: um triângulo para baixo significa que a região é expandida, enquanto se carregar nele irá recolher a região e ficará então visível um triângulo para a direita em alternativa.</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 dobradas são recordadas quando fechar um ficheiro; assim, quando o reabrir, os nós dobrados irão continuar dessa forma. Isto aplica-se também às operações de recarregamento.</para>

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

</sect1>

<sect1 id="advanced-editing-tools-scripting">
<title
>Extender 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 programas. A linguagem de programação é o ECMAScript (vulgarmente conhecido como JavaScript). O &kappname; suporta dois tipos de programas: os de indentação e os de linha de comandos. </para>

<sect2 id="advanced-editing-tools-scripting-indentation">
<title
>Programas de Indentação</title>

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

<para
>As seguintes secções descrevem, passo-a-passo, como criar o esqueleto de um módulo de indentação simples. Como primeiro passo, crie um novo ficheiro <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 Programa de Indentação</title>
<para
>O cabeçalho do ficheiro <filename
>javascript.js</filename
> está incorporado num comentário e tem o seguinte formato <programlisting>
/* kate-script
 * name: JavaScript
 * author: Nome de Exemplo &lt;nome.exemplo@um.endereco.org&gt;
 * license: BSD
 * revision: 1
 * kate-version: 3.4
 * type: indentation
 * required-syntax-style: javascript
 * indent-languages: javascript
 * priority: 0
 * i18n-catalog: meu-catalogo
 *
 * Uma linha sem o símbolo ':' interrompe o processamento do cabeçalho. Isto é, poderá
 * adicionar mais algum texto aqui como, por exemplo, uma licença detalhada.
 */
</programlisting
> Cada item será agora explicado em detalhe: <itemizedlist>
<listitem
><para
><literal
>kate-script</literal
> [obrigatório]: Este texto tem de aparecer na primeira linha do ficheiro <filename
>*.js</filename
>, caso contrário o &kappname; irá ignorar o programa. </para
></listitem>
<listitem
><para
><literal
>name</literal
> [obrigatório]: Este é o nome do modo de indentação que aparece no menu <menuchoice
><guimenu
>Ferramentas</guimenu
><guimenuitem
>Indentação</guimenuitem
></menuchoice
> e na janela de configuração. </para
></listitem>
<listitem
><para
><literal
>author</literal
> [opcional]: O nome e a informação de contacto 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]: Uma lista, separada por vírgulas, dos estilos de realce de sintaxe obrigatórios. Isto é importante para os módulos de indentação que se baseiam em alguma informação específica de realce no documento. Se for indicado um estilo de sintaxe obrigatório, o módulo só ficará disponível quando estiver o realce apropriado seleccionado. Isto evita algum <quote
>comportamento indefinido</quote
> causado pela utilização da indentação sem o esquema de realce esperado. Por exemplo, a indentação de Ruby tira partido disto nos ficheiros <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 indentar correctamente, p.ex.: c++, java. </para
></listitem>
<listitem
><para
><literal
>priority</literal
> [opcional]: Se existirem vários módulos de indentação adequados para um determinado ficheiro de realce, este campo decide qual deverá ser usado por omissão. </para
></listitem>
<listitem
><para
><literal
>i18n-catalog</literal
> [opcional]: Catálogo de mensagens adicional (ficheiro <literal
>.po</literal
>) carregado para a tradução de indentaçõ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 da Indentação</title>
<para
>Tendo definido o cabeçalho, esta secção explica como é que funciona a programação de indentações em si. O esqueleto básico do código parece-se com o seguinte: <programlisting>
require("range.js");

caracteresActivacao = "{}/:;";
function indent(linha, larguraIndentacao, caracter)
{
    // invocado para cada linha nova (caracter == '\n') e todos os caracteres indicados na
    // variável global 'caracteresActivacao'. Ao invocar o <menuchoice
><guimenu
>Ferramentas</guimenu
><guimenuitem
>Alinhar</guimenuitem
></menuchoice>
    // a variável 'caracter' está em branco, i.e. caracter == ''.
    //
    // 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 indentada</para
></listitem
> <listitem
><para
><literal
>larguraIndentacao</literal
>: o número de espaços correspondentes a cada indentação</para
></listitem
> <listitem
><para
><literal
>caracter</literal
>: ou um carácter de mudança de linha (<literal
>ch == '\n'</literal
>), algum dos caracteres de activação indicados em <literal
>caracteresActivacao</literal
> ou vazio, caso o utilizador tenha invocado a acção <menuchoice
><guimenu
>Ferramentas</guimenu
><guimenuitem
>Alinhar</guimenuitem
></menuchoice
>.</para
></listitem
> </itemizedlist
> O valor devolvido pela função <function
>indent()</function
> define como é que a linha será indentada. 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 a indentação (procura pela linha não-vazia anterior)</para
></listitem
> <listitem
><para
>valor devolvido <literal
> 0</literal
>: números &gt;= 0 definem a largura de indentação em espaços</para
></listitem
> </itemizedlist
> Em alternativa, poderá ser devolvida uma lista com dois elementos: <itemizedlist
> <listitem
><para
><literal
>return [ indentação, alinhamento ];</literal
></para
></listitem
> </itemizedlist
> Nesse caso, o primeiro elemento é a profundidade de indentação, tendo o mesmo significado que os valores especiais. Contudo, o segundo elemento é um valor absoluto que representa uma coluna para o <quote
>alinhamento</quote
>. Se este valor for maior que o valor de indentação, a diferença representa um número de espaços a adicionar após a indentação do primeiro parâmetro. Caso contrário, o segundo número será ignorado. A utilização de tabulações e espaços na indentação é normalmente referida como sendo um <quote
>modo misto</quote
>. </para>

<para
>Considere o seguinte exemplo: Assuma que usa as tabulações para indentar, 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 indentar a linha 2, a função <function
>indent()</function
> devolve [8, 15]. Em função disso, são introduzidas duas tabulações para indentar até à coluna 8, e são introduzidos 7 espaços para alinhar o segundo parâmetro com o primeiro, de modo a permanecer alinhado, caso o ficheiro seja visto com outro tamanho de tabulação. </para>

<para
>Uma instalação predefinida do KDE fornece o &kappname; com vários módulos de indentação. O código-fonte correspondente em JavaScript poderá ser encontrado em <filename
>$KDEDIR/share/apps/katepart/script/indentation</filename
>. </para>

<para
>A criação de um módulo de indentação necessita que actualize os programas, de modo a ver se as alterações se comportam de forma adequada. Em vez de reiniciar a aplicação, basta ir para a linha de comandos e invocar o comando <command
>reload-scripts</command
>. </para>

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

</sect3>
</sect2>

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

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

<para
>Os programas da linha de comandos estão localizados na mesma pasta que os programas de indentação. Como tal, como primeiro passo, crie um ficheiro <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 Comandos</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@um.endereco.org&gt;
 * license: BSD
 * revision: 1
 * kate-version: 3.4
 * type: commands
 * functions: sort, format-paragraph
 * i18n-catalog: meu-catalogo
 *
 * Uma linha sem o símbolo ':' interrompe o processamento do cabeçalho. Isto é, poderá adicionar
 * algum texto opcional aqui como, por exemplo, uma licença detalhada.
 */
</programlisting
> Cada um dos elementos será explicado em detalhe: <itemizedlist>
<listitem
><para
><literal
>kate-script</literal
> [obrigatório]: Este texto tem de aparecer na primeira linha do ficheiro <filename
>*.js</filename
>, caso contrário o &kappname; irá ignorar o programa.</para
></listitem>
<listitem
><para
><literal
>author</literal
> [opcional]: O nome e a informação de contacto 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 (ficheiro <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 comandos 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 ficheiro de programa do exemplo acima tem de 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, p.ex. o range.js se usar o Range
require ("range.js");

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

<para
>Os argumentos na linha de comandos são passados à função como <parameter
>arg1</parameter
>, <parameter
>arg2</parameter
>, etc. Para poder fornecer a documentação para cada comando, basta implementar a função '<function
>help</function
>' da seguinte forma: <programlisting>
function help(comando)
{
    if (comando == "ordenar") {
        return i18n("Ordena o texto seleccionado.");
    } else if (cmd == "...") {
        // ...
    }
}
</programlisting
> Se executar <command
>help ordenar</command
> na linha de comandos, irá invocar esta função 'help' com o argumento <parameter
>comando</parameter
> configurado com o comando indicado, i.e. <parameter
>comando == "ordenar"</parameter
>. O &kappname; irá então apresentar o texto devolvido como documentação para o utilizador. Certifique-se que <link linkend="advanced-editing-tools-scripting-api-i18n"
>traduz 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á de fornecer uma chamada chamada <literal
>action</literal
> da seguinte forma: <programlisting>
function action(comando)
{
    var a = new Object();
    if (comando == "ordenar") {
        a.text = i18n("Ordenar o Texto Seleccionado");
        a.icon = "";
        a.category = "";
        a.interactive = false;
        a.shortcut = "";
    } else if (comando == "descerLinhas") {
        // repetir para a acção seguinte
    }
    return a;
}
</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 terá de indicar no objecto de JavaScript devolvido: <itemizedlist>
<listitem
><para
><literal
>a.text</literal
> [obrigatório]: O texto que aparece no menu <guimenu
>Ferramentas</guimenu
> &gt; <guimenu
>Programas</guimenu
>. Certifique-se que usa o <literal
>i18n</literal
> para as traduções.</para
></listitem>
<listitem
><para
><literal
>a.icon</literal
> [opcional]: O ícone aparece a seguir ao texto no menu. Todos os nomes de ícones do KDE poderão ser aqui usados.</para
></listitem>
<listitem
><para
><literal
>a.category</literal
> [opcional]: Se for indicada uma categoria, o programa aparece num submenu. Certifique-se que usa o <literal
>i18n</literal
> para as traduções.</para
></listitem>
<listitem
><para
><literal
>a.interactive</literal
> [opcional]: Se o programa precisa de interacção por parte do utilizador, 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 predefinido. 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 comandos obriga a actualizar os programas, de modo a ver se as alterações funcionam apropriadamente. Em vez de reiniciar a aplicação, basta mudar para a linha de comandos e invocar o comando <command
>reload-scripts</command
>. </para>

<para
>Se criar programas úteis, por favor considere a hipótese de contribuir com eles para o Projecto do &kappname;, <ulink url="mailto:kwrite-devel@kde.org"
>contactando para tal 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 programas, i.e. os programas de indentação e os comandos da consola. O <classname
>Cursor</classname
> e o <classname
>Range</classname
> são fornecidos através de ficheiros de bibliotecas no <filename
>$KDEDIR/share/apps/katepart/libraries</filename
>. Se quiser usá-los no seu programa, o que será necessário para usar algumas das funções do <classname
>Document</classname
> ou do <classname
>View</classname
>, inclua por favor a biblioteca necessária, usando: <programlisting
>// bibliotecas em JS do katepart necessárias, p.ex. o "range.js" se usar o Range
require ("range.js");
</programlisting>
</para>

<para
>Para extender a API-padrão de programação com funções e protótipos próprio, basta criar um ficheiro novo na pasta de configuração local do KDE, em <filename
>$KDEHOME/share/apps/katepart/libraries</filename
> e inclua-a no seu programa, usando: <programlisting
>require ("nome-do-meu-programa.js");
</programlisting>

</para>

<para
>Para extender os protótipos existentes, como o <classname
>Cursor</classname
> ou o <classname
>Range</classname
>, a forma recomendada é <emphasis
>não</emphasis
> modificar os ficheiros <filename
>*.js</filename
> globais. Em vez disso, altere o protótipo do <classname
>Cursor</classname
> em JavaScript, após o <filename
>cursor.js</filename
> que é incluído no seu programa com o <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 secções seguintes. </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 a seguir ao 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 <constant
>true</constant
> (verdadeiro) se este intervalo contiver a posição do cursor, caso contrário devolve <constant
>false</constant
>. </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
> partilharem 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 começar e acabar na mesma linha. </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 secção apresenta todas as funções globais.</para>


<sect4 id="advanced-editing-tools-scripting-api-includes">
<title
>Ler &amp; Incluir os Ficheiros</title>

<variablelist
><varlistentry>
<term
><synopsis
>String read(<parameter
>String <replaceable
>ficheiro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Irá procurar pelo <replaceable
>ficheiro</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
>ficheiro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Irá procurar pelo <replaceable
>ficheiro</replaceable
> indicado em relação à pasta <literal
>katepart/script/libraries</literal
> e este será avaliado. O <literal
>require</literal
> está protegido internamente contra inclusões múltiplas do mesmo <replaceable
>ficheiro</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 na consola 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 exactamente 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. Por outras palavras, como programador do &kappname;, não terá de se preocupar com a extracção e tradução das mensagens. Contudo, para programas de terceiros, desenvolvidos fora do KDE, terá de extrair e traduzir você mesmo a as mensagens. Em conjunto com os seus programas, terá de distribuir também um catálogo de traduções que inclui todos os textos traduzidos. Para além disso, o cabeçalho do seu programa terá de indicar explicitamente o catálogo a carregar com a indicação do <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. Para ale´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á a ser executado, existe uma variável global <quote
><literal
>view</literal
></quote
> que representa a área de edição activa 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 actual 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 actual 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 actual. </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 actual 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 seleccionado. Se não estiver nenhum texto seleccionado, o texto devolvido vem vazio. </para
></listitem>
</varlistentry>


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


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


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


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


<varlistentry>
<term
><synopsis
>void view.selectAll();
</synopsis
></term>
<listitem
><para
>Selecciona o texto por inteiro no documento. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void view.clearSelection();
</synopsis
></term>
<listitem
><para
>Limpa a selecção de texto actual, 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á a executar um programa, existe uma variável global <quote
><literal
>document</literal
></quote
> que representa o documento activo 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 ficheiro do documento, ou então um texto vazio para as janelas de texto ainda por gravar. </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 gravar. </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 actualmente para gravar o ficheiro. </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
>posição</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 <constant
>true</constant
> (verdadeiro) se o documento tiver algumas alterações por gravar, caso contrário devolve <constant
>false</constant
>. </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 carácter 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
>ateLinha</replaceable
></parameter
>, <parameter
>int <replaceable
>ateColuna</replaceable
></parameter
>);
String document.text(<parameter
>Cursor <replaceable
>de</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>ate</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 com Range.isValid()), caso a posição do texto esteja após o fim de uma linha. Se não existir nenhuma palavra no cursor indicado, é devolvido um intervalo vazio. </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 carácter 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 carácter da <replaceable
>linha</replaceable
> indicada que não seja um espaço em branco. O primeiro carácter encontra-se na coluna 0. Se a linha estiver em branco ou só tiver espaços em branco, o texto devolvido vem vazio. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.lastChar(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o último carácter da <replaceable
>linha</replaceable
> indicada que não seja um espaço em branco. O primeiro carácter encontra-se na coluna 0. Se a linha estiver em branco ou só tiver espaços em branco, o texto devolvido vem vazio. </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 carácter 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
>ateLinha</replaceable
></parameter
>, <parameter
>int <replaceable
>ateColuna</replaceable
></parameter
>);
bool document.removeText(<parameter
>Cursor <replaceable
>de</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>ate</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 que invoca sempre o <function
>editEnd()</function
> tantas vezes como 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
>carácter</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 <constant
>true</constant
> (verdadeiro) se o <replaceable
>carácter</replaceable
> indicado com o <replaceable
>atributo</replaceable
> indicado for adequado para mudar de linha, caso contrário devolve <constant
>false</constant
>. </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 ficheiros 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
>Altera o valor da variável do documento identificada pela <replaceable
>chave</replaceable
>. Devolve o valor da variável alterada. </para>
<para
>Ver 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 carácter 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 carácter 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, devolvendo um objecto inteiro ou um 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
>, devolvendo um objecto inteiro ou um 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 carácter indicado, começando na posição do cursor indicada. Por exemplo, se for passado o '(', como carácter, esta função irá devolve a posição do '(' de abertura. Isto implica uma contagem das referências, i.e., os outros '(...)' são ignorados. </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 predefinido 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 carácter 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 carácter 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 carácter 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 carácter 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 carácter 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>
