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

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

<title
>Comentar/Descomentar</title>

<para
>Os comandos Comentar e Descomentar, disponíveis no menu <guimenu
>Ferramentas</guimenu
> permitem-lhe adicionar ou remover marcações de comentários à seleção ou à linha atual, se não existir texto selecionado, se os comentários são suportados pelo formato do texto que você está editando.</para>

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

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

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

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

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

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

</sect1>

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

<para
>O componente de edição do &kate; possui uma linha de comando interna, que lhe permite efetuar várias ações a partir de uma interface mínima. A linha de comando é um campo de texto no fundo da área de edição onde, para mostrá-la, você poderá selecionar a opção <menuchoice
><guimenu
>Ver</guimenu
><guimenuitem
>Alternar para Linha de Comando</guimenuitem
></menuchoice
> ou usar o atalho (que é, por padrão, o <keycombo action="simul"
><keycap
>F7</keycap
></keycombo
>). O editor oferece um conjunto de comandos, tal como está documentado abaixo, sendo oferecidos mais comandos através de plug-ins.</para>

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

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

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

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

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

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

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

<varlistentry>
<term
>BOOLEANO</term>
<listitem
><para
>Isto é usado com os comandos que ativam ou desativam certas coisa. 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</para
></listitem>
</varlistentry>

</variablelist>

<variablelist>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<varlistentry>
<term
><cmdsynopsis
><command
>set-highlight</command
><arg
>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>

</variablelist>

</sect3>

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

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

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

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

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

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

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

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

<varlistentry>
<term
><cmdsynopsis
><command
>replace</command
><arg
>padrão</arg
><arg
>substituição</arg
></cmdsynopsis
></term>
<listitem
><para
>Substitui o texto correspondente ao <userinput
>padrão</userinput
> por <userinput
>substituição</userinput
>. Se você quiser incluir espaços em branco no <userinput
>padrão</userinput
>, deverá colocar tanto o <userinput
>padrão</userinput
> como a <userinput
>substituição</userinput
> entre aspas simples ou duplas. Se os argumentos não estiverem entre estes caracteres, a primeira palavra é usada como <userinput
>padrão</userinput
> e o resto como a <userinput
>substituição</userinput
>. Se a <userinput
>substituição</userinput
> estiver em branco, cada ocorrência do <userinput
>padrão</userinput
> será removida.</para>
<para
>Você poderá configurar opções para modificar a procura, adicionando dois pontos (:), seguidos de uma ou mais letras, onde cada uma representa uma configuração, o que corresponderá ao formato <userinput
>replace:opções padrão substituição</userinput
>. As opções disponíveis são: <variablelist>

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

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

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

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

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

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

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

</variablelist>

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

<varlistentry>
<term
><cmdsynopsis
><command
>date</command
><arg
>formato</arg
></cmdsynopsis
></term>
<listitem
><para
>Insere um texto de data/hora, tal como está definido pelo <userinput
>formato</userinput
> indicado, ou com o formato <quote
>aaaa-MM-dd hh:mm:ss</quote
>, se não for indicada qualquer formatação. As traduções a seguir são feitas quando for interpretado o <userinput
>formato</userinput
>: <informaltable
> <tgroup cols="2"
> <tbody>
<row
><entry
><literal
>d</literal
></entry
><entry
>O dia, como um número sem um zero inicial (1-31).</entry
></row>
<row
><entry
><literal
>dd</literal
></entry
><entry
>O dia, como um número com um zero inicial (01-31).</entry
></row>
<row
><entry
><literal
>ddd</literal
></entry
><entry
>O nome do dia abreviado, no formato regional (p.ex. 'Seg'..'Dom').</entry
></row>
<row
><entry
><literal
>dddd</literal
></entry
><entry
>O nome do dia completo, no formato regional (p.ex. 'Segunda'..'Domingo').</entry
></row>
<row
><entry
><literal
>M</literal
></entry
><entry
>O mês, como um número sem um zero inicial (1-12).</entry
></row>
<row
><entry
><literal
>MM</literal
></entry
><entry
>O mês, como um número com um zero inicial (01-12).</entry
></row>
<row
><entry
><literal
>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
>identificador</arg
></cmdsynopsis
></term>
<listitem>
<para
>Este comando permite que você insira caracteres literais através de suas identificações numéricas, em decimal, octal ou hexadecimal. Para usá-lo, abra o diálogo de Edição de Comando e digite <userinput
>char: [número]</userinput
> na caixa de entrada e clique em <guibutton
>OK</guibutton
>.</para>

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

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

</listitem>
</varlistentry>

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

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

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

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

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

<example>

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

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

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

</example>

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

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

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

</example>

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

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

<para
>Suponha que você possui a seguinte linha: <programlisting
>void MinhaClasse::DoStringOps( String      &amp;foo, String &amp;bar String *p, int  &amp;a, int &amp;b )</programlisting>
</para>
<para
>Agora, você pode perceber que este não é um código bom, e decidir que deseja usar a palavra-chave <constant
>const</constant
> para todos os argumentos  <quote
>address of</quote
>, aqueles caracterizados pelo operador  &amp; em frente ao nome do argumento. Você poderia também simplificar o espaço em branco, pois assim existiria somente um caractere de espaço em branco entre cada palavra.</para>

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

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

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

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

</example>

</listitem>

</varlistentry>

</variablelist>

</sect3>

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

<variablelist>

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

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

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

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

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

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

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

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

</variablelist>

</para>

</listitem>

</varlistentry>

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

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

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

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

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

</variablelist>

</sect3>

</sect2>

</sect1>

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

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

<para
>Para usar a funcionalidade de desdobramento de código, ative os marcadores com a opção <menuchoice
><guimenu
>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 da tela, mostra uma visão gráfica sobre as regiões que poderão ser recolhidas ou expandidas, com símbolos triangulares para indicar a operação possível numa determinada região: um triângulo para baixo significa que a região é expandida; clicar sobre ele irá recolher a região, clicar em um triângulo para direita irá espandí-la.</para>

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

</sect1>

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

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

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

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

<para
>As seções a seguir descrevem, passo-a-passo, como criar o esqueleto de um módulo de recuo simples. Como primeiro passo, crie um novo arquivo <filename
>*.js</filename
>, chamado por exemplo <filename
>javascript.js</filename
> na pasta pessoal local <filename
>$KDEHOME/share/apps/katepart/script</filename
>. </para>

<sect3 id="advanced-editing-tools-scripting-indentation-header">
<title
>O cabeçalho do script de recuo</title>
<para
>O cabeçalho do arquivo <filename
>javascript.js</filename
> está incorporado num comentário e possui o seguinte formato <programlisting>
/* kate-script
 * name: JavaScript
 * author: Nome de Exemplo &lt;nome.exemplo@endereco.org&gt;
 * license: BSD
 * revision: 1
 * kate-version: 3.4
 * type: indentation
 * required-syntax-style: javascript
 * indent-languages: javascript
 * priority: 0
 *
 * Uma linha sem o símbolo ':' interrompe o processamento do cabeçalho. Isto é, poderá
 * adicionar mais algum texto aqui como, por exemplo, uma licença detalhada.
 */
</programlisting
> Cada item será agora explicado em detalhe: <itemizedlist>
<listitem
><para
><literal
>kate-script</literal
> [obrigatório]: Este texto tem que aparecer na primeira linha do arquivo <filename
>*.js</filename
>, caso contrário o &kate; irá ignorar o programa. </para
></listitem>
<listitem
><para
><literal
>name</literal
> [obrigatório]: Este é o nome do modo de recuo que aparece no menu <menuchoice
><guimenu
>Ferramentas</guimenu
><guimenuitem
>Recuar</guimenuitem
></menuchoice
> e na janela de configuração. </para
></listitem>
<listitem
><para
><literal
>author</literal
> [opcional]: O nome e a informação de contato do autor. </para
></listitem>
<listitem
><para
><literal
>license</literal
> [opcional]: Forma curta da licença, como por exemplo BSD ou LGPLv3. </para
></listitem>
<listitem
><para
><literal
>revision</literal
> [obrigatório]: A versão do programa. Este número deverá ser aumentado sempre que o programa for modificado. </para
></listitem>
<listitem
><para
><literal
>kate-version</literal
> [obrigatório]: A versão mínima do &kate; necessária. </para
></listitem>
<listitem
><para
><literal
>type</literal
> [obrigatório]: O tipo deverá ser <quote
><literal
>indentation</literal
></quote
>, caso contrário, o &kate; irá ignorar este script. </para
></listitem>
<listitem
><para
><literal
>required-syntax-style</literal
> [opcional]: Lista separa por vírgulas dos estilos de realce de sintaxe necessários. Isto é importante para recuadores que se baseiam em informações de realce no documento. Se uma determinada realce de sintaxe dor especificada, o recuador estará disponível somente quando a realce de sintaxe apropriada estiver ativa. Isto evite um <quote
>comportamento inesperado</quote
> causado pelo uso do recuador sem o esquema de realce esperado. Por exemplo, o recuado do Ruby faz uso dos arquivos <filename
>ruby.js</filename
> e <filename
>ruby.xml</filename
>. </para
></listitem>
<listitem
><para
><literal
>indent-languages</literal
> [opcional]: Uma lista, separada por vírgulas, de estilos de sintaxe que este módulo consegue recuar corretamente, p.ex.: c++, java. </para
></listitem>
<listitem
><para
><literal
>priority</literal
> [opcional]: Se existirem vários módulos de recuo adequados para um determinado arquivo de realce, este campo decide qual deverá ser usado por padrão. </para
></listitem>
</itemizedlist>
</para>

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

</sect3>

<sect3 id="advanced-editing-tools-scripting-indentation-body">
<title
>O código fonte do recuador</title>
<para
>Tendo definido o cabeçalho, esta seção explica como funciona a programação de recuadores em si. O esqueleto básico do código parece-se com o seguinte: <programlisting>
caracteresAtivacao = "{}/:;";
function indent(linha, larguraRecuo, caractere)
{
    // invocado para cada linha nova (caractere == '\n') e todos os caracteres indicados na
    // variável global 'caracteresAtivacao'. Ao invocar o <menuchoice
><guimenu
>Ferramentas</guimenu
><guimenuitem
>Alinhar</guimenuitem
></menuchoice>
    // a variável 'caractere' está em branco, i.e. caractere == ''.
    //
    // ver também: API de Programação
    return -2;
}
</programlisting
> A função <function
>indent()</function
> tem três parâmetros: <itemizedlist
> <listitem
><para
><literal
>linha</literal
>: a linha que tem de ser recuada</para
></listitem
> <listitem
><para
><literal
>larguraRecuo</literal
>: o número de espaços correspondentes a cada recuo</para
></listitem
> <listitem
><para
><literal
>caractere</literal
>: ou um caractere de mudança de linha (<literal
>ch == '\n'</literal
>), algum dos caracteres de ativação indicados em <literal
>caracteresAtivacao</literal
> ou vazio, caso o usuário tenha invocado a ação <menuchoice
><guimenu
>Ferramentas</guimenu
><guimenuitem
>Alinhar</guimenuitem
></menuchoice
>.</para
></listitem
> </itemizedlist
> O valor devolvido pela função <function
>indent()</function
> define como a linha será recuada. Se o valor devolvido for um número inteiro, é interpretado da seguinte forma: <itemizedlist
> <listitem
><para
>valor devolvido <literal
>-2</literal
>: não fazer nada</para
></listitem
> <listitem
><para
>valor devolvido <literal
>-1</literal
>: mantém o recuo (procura pela linha não-vazia anterior)</para
></listitem
> <listitem
><para
>valor devolvido <literal
> 0</literal
>: números &gt;= 0 definem a largura do recuo em espaços</para
></listitem
> </itemizedlist
> Em alternativa, poderá ser devolvida uma lista com dois elementos: <itemizedlist
> <listitem
><para
><literal
>return [ recuo, alinhamento ];</literal
></para
></listitem
> </itemizedlist
> Nesse caso, o primeiro elemento é a profundidade de recuo, tendo o mesmo significado que os valores especiais. Contudo, o segundo elemento é um valor absoluto que representa uma coluna para o <quote
>alinhamento</quote
>. Se este valor for maior que o valor do recuo, a diferença representa um número de espaços a adicionar após o recuo do primeiro parâmetro. Caso contrário, o segundo número será ignorado. A utilização de tabulações e espaços nos recuos é normalmente referida como sendo um <quote
>modo misto</quote
>. </para>

<para
>Considere o seguinte exemplo: Considerando que são usadas as tabulações para recuar, e que o tamanho da tabulação é de 4. Aqui, o &lt;tab&gt; representa uma tabulação e o '.' representa um espaço: <programlisting>
1: &lt;tab&gt;&lt;tab&gt;xpto("olá",
2: &lt;tab&gt;&lt;tab&gt;......."mundo");
</programlisting
> Ao recuar a linha 2, a função <function
>indent()</function
> devolve [8, 15]. Em função disso, são introduzidas duas tabulações para recuar até à coluna 8, e são introduzidos 7 espaços para alinhar o segundo parâmetro com o primeiro, de modo a permanecer alinhado, caso o arquivo seja visto com outro tamanho de tabulação. </para>

<para
>Uma instalação padrão do KDE fornece o &kate; com vários módulos de recuo. O código fonte correspondente em JavaScript poderá ser encontrado em <filename
>$KDRDIR/share/apps/katepart/script</filename
>. </para>

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

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

</sect3>
</sect2>

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

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

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

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

<para
>O &kate; 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 &kate; através da <link linkend="advanced-editing-tools-commandline"
>linha de comando incorporada</link
>. </para>
</sect3>

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

<para
>Todas as funções indicadas no cabeçalho terão de estar implementadas no programa. Por exemplo, o arquivo de programa do exemplo acima tem que implementar as duas funções <command
>ordenar</command
> e <command
>formatar-paragrafo</command
>. Todas as funções têm a seguinte sintaxe: <programlisting
>function &lt;nome&gt;(arg1, arg2, ...)
{
    // ... implementação, ver também: API de Programação
}
</programlisting>
</para>

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

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

<para
>Se você criar programas úteis, por favor considere a hipótese de contribuir com eles para o Projeto do &kate;, <ulink url="mailto:kwrite-devel@kde.org"
>contactando para isso a lista de correio</ulink
>. </para>
</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. tanto os de recuo como os da linha de comando. Antes de carregar o conteúdo de um programa, o &kate; adiciona primeiro vários protótipos e funções ao contexto do programa. Esta API de conveniência contém protótipos para alguns itens, como os cursores e intervalos de texto, estando localizada na pasta <filename
>$KDEDIR/share/apps/katepart/api</filename
>. Aí, os nomes de cada um dos arquivos de JavaScript estão em conformidade com a seguinte nomenclatura: <programlisting>
&lt;número&gt;_&lt;nome&gt;.js
</programlisting
> O número tem dois algarismos e o nome pode ser arbitrário, como por exemplo <quote
><filename
>utilitários</filename
></quote
>. Através do número, o &kate; controla a ordem de execução da API. I.e., o arquivo chamado <filename
>05_cursor.js</filename
> é invocado antes do arquivo <filename
>10_range.js</filename
>. (Isto é semelhante à ordem de inicialização do sistema 'init' do Linux). </para>

<para
>Para extender a API-padrão de programação com funções e protótipos próprios, basta criar um arquivo novo na pasta de configuração local do KDE, em <filename
>$KDEHOME/share/apps/katepart/api</filename
> e garantir que tem um número (ordem de execução) maior que os outros arquivos <filename
>*.js</filename
> da pasta global em <filename
>$KDEDIR/share/apps/katepart/api</filename
>. O &kate; procura automaticamente em ambas as pastas por arquivos <filename
>*.js</filename
> e executa-os na ordem correta. </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 arquivos <filename
>*.js</filename
> globais. Em vez disso, crie um arquivo <filename
>*.js</filename
> na pasta local que seja executado após o <filename
>05_cursor.js</filename
> e altere depois o protótipo <classname
>Cursor</classname
> no JavaScript. </para>

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

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

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

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


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>

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


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


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


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


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


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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-debug">
<title
>Funções Globais</title>

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


</sect3>

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


<variablelist
><varlistentry>
<term
><synopsis
><function
>void view.setCursorPosition(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>)</function>
<function
>void view.setCursorPosition(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>)</function
>
</synopsis
></term>
<listitem
><para
>Devolve a posição atual do cursor na janela.</para
></listitem>
</varlistentry
></variablelist>


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


<variablelist
><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
></variablelist>


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


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


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


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


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


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


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


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

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


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


<variablelist
><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
></variablelist>


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

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

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

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

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


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


<variablelist
><varlistentry>
<term
><synopsis
>String document.text(<parameter
>int <replaceable
>daLinha</replaceable
></parameter
>, <parameter
>int <replaceable
>daColuna</replaceable
></parameter
>, <parameter
>int <replaceable
>paraLinha</replaceable
></parameter
>, <parameter
>int <replaceable
>paraColuna</replaceable
></parameter
>);
String document.text(<parameter
>Cursor <replaceable
>de</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>para</replaceable
></parameter
>);
String document.text(<parameter
>Range <replaceable
>intervalo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o texto no intervalo indicado. Recomenda-se que use a versão baseada nos cursores e nos intervalos, de modo a ter uma melhor visibilidade do código-fonte. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


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


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


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


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


<variablelist
><varlistentry>
<term
><synopsis
>bool document.matchesAt(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>, <parameter
>int <replaceable
>linha</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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


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


<variablelist
><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
></variablelist>


<variablelist
><varlistentry>
<term
><synopsis
>bool document.insertText(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>, <parameter
>int <replaceable
>linha</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
></variablelist>


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


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


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


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


<variablelist
><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
></variablelist>


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


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
>caracter</replaceable
> e <replaceable
>atributo</replaceable
> indicados possam fazer parte de uma palavra, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><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
>caracter</replaceable
> indicado com o <replaceable
>atributo</replaceable
> indicado for adequado para mudar de linha, caso contrário devolve <constant
>false</constant
>. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>



<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


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


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>



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


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


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


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


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


<variablelist
><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
></variablelist>


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


<variablelist
><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
></variablelist>



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


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


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


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


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

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