<chapter id="dev">
<chapterinfo>
<authorgroup>
<author
>&TC.Hollingsworth; &TC.Hollingsworth.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
> <othercredit role="translator"
><firstname
>André Marcelo</firstname
><surname
>Alvarenga</surname
><affiliation
><address
><email
>alvarenga@kde.org</email
></address
></affiliation
><contrib
>Tradução</contrib
></othercredit
>
</authorgroup>
</chapterinfo>
<title
>Ampliando o &katepart;</title>
<sect1 id="dev-intro">
<title
>Introdução</title>
<para
>Como em qualquer componente de editor de texto avançado, o &katepart; oferece uma grande variedade de formas para ampliar suas funcionalidades. Você pode <link linkend="dev-scripting"
>criar scripts simples para adicionar funcionalidades com o JavaScript</link
> Finalmente, assim que tiver ampliado as funcionalidades do &katepart;, sinta-se a vontade para <ulink url="http://kate-editor.org/join-us/"
>se juntar a nós</ulink
> e compartilhar as suas melhorias com o mundo!</para>
</sect1>
<sect1 id="highlight">
<title
>Trabalhando com Realce de Sintaxe</title>
<sect2 id="highlight-overview">
<title
>Introdução</title>
<para
>O Realce de Sintaxe é o que faz com que o editor exiba automaticamente o texto em diferentes cores/estilos, dependendo da função da string em questão para o propósito do arquivo. No código-fonte do programa, por exemplo, declarações de controle pode ser renderizadas em negrito, enquanto tipos de dados e comentários ficam com cores diferentes do restante do texto. Isto aumenta consideravelmente a legibilidade do texto e assim, o autor pode ser mais eficiente e produtivo.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="highlighted.png"/></imageobject>
<textobject
><phrase
>Uma função Perl, representada com realce de sintaxe.</phrase
></textobject>
<caption
><para
>Uma função Perl, representada com realce de sintaxe.</para>
</caption>
</mediaobject>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="unhighlighted.png"/></imageobject>
<textobject
><phrase
>A mesma função Perl, sem realce de sintaxe.</phrase
></textobject>
<caption
><para
>A mesma função Perl, sem realce de sintaxe.</para
></caption>
</mediaobject>
<para
>Dos dois exemplos, qual é o mais fácil de ler?</para>
<para
>O &kappname; vem com um sistema flexível, configurável e capaz de fazer realce de sintaxe; a distribuição padrão oferece definições para um vasto conjunto de linguagens de programação, de manipulação e de 'scripting', bem como para outros formatos de texto. Além disso, você pode criar as suas próprias definições em arquivos &XML; simples.</para>
<para
>O &kappname; detectará automaticamente regras de realce de sintaxe quando você abrir um arquivo, baseado no tipo &MIME; do arquivo, determinado pela extensão ou, se não existir, pelo conteúdo. Se você não conseguir, ajuste manualmente a sintaxe para o uso no menu <menuchoice
><guimenu
>Ferramentas</guimenu
><guisubmenu
>Realçar</guisubmenu
></menuchoice
>.</para>
<para
>Os estilos e cores usados por cada definição de realce de sintaxe podem ser configurados usando a página de <link linkend="prefcolors-highlighting-text-styles"
>Estilos de Realce de Texto</link
> da <link linkend="config-dialog"
>Janela de Configuração</link
>; por outro lado, os tipos &MIME; e as extensões de arquivos para os quais deve ser usada, podem ser configurados usando a página de <link linkend="pref-open-save-modes-filetypes"
>Modos & Tipos de Arquivo</link
>.</para>
<note>
<para
>O realce de sintaxe existe para aumentar a legibilidade do texto correto, mas não se pode confiar nisto para validar seu texto. Marcar o texto para sintaxe é difícil, dependendo do formato que você está usando e, em alguns casos, os autores das regras de sintaxe ficarão orgulhosos se 98% do texto é renderizado corretamente, embora muito frequentemente você precise de um estilo raro para ver os 2% incorretos.</para>
</note>
<tip>
<para
>Você pode baixar as definições de sintaxe adicionais ou atualizadas na página Web do &kappname; clicando no botão <guibutton
>Baixar Arquivos de Sintaxe...</guibutton
> na página <link linkend="pref-open-save-modes-filetypes"
>Modos & Tipos de Arquivo</link
> da <link linkend="config-dialog"
>Janela de Configuração</link
>.</para>
</tip>
</sect2>
<sect2 id="katehighlight-system">
<title
>O Sistema de Realce de Sintaxe do &kappname;</title>
<para
>Esta seção irá discutir o realce de sintaxe do &kappname; em detalhes. É para você, caso deseje saber mais sobre esta funcionalidade ou se quiser criar ou alterar as definições de sintaxe.</para>
<sect3 id="katehighlight-howitworks">
<title
>Como funciona</title>
<para
>Sempre que você abrir um arquivo, uma das primeiras coisas que o editor &kappname; faz é detectar qual definição de sintaxe deve ser usada para o arquivo. Ao ler o texto do arquivo, e enquanto você digita no arquivo, o sistema de realce de sintaxe analisará o texto usando as regras definidas pela definição de sintaxe, e marcará no texto onde contexto e estilos diferentes iniciarem e finalizarem.</para>
<para
>Quando você escrever no documento, o novo texto será analisado e marcado na hora, pois se você remover um caractere que está marcado como início ou fim de um contexto, o estilo em volta do texto modifica de acordo com ele.</para>
<para
>As definições de sintaxe usadas pelo sistema de realce de sintaxe do &kappname; são arquivos &XML; que contém <itemizedlist>
<listitem
><para
>Regras para a detecção do texto inteiro, organizado em blocos de contexto</para
></listitem>
<listitem
><para
>Listas de palavras-chave</para
></listitem>
<listitem
><para
>Definições de Item de Estilo</para
></listitem>
</itemizedlist>
</para>
<para
>Ao analisar o texto, as regras de detecção serão avaliadas na ordem em que foram definidas, e se o início da string atual coincidir com uma regra, o contexto relacionado será usado. O ponto de partida no texto é movido para o ponto final no local onde aquela regra coincide, e um novo loop de regras inicia, começando no contexto configurado pela regra relacionada.</para>
</sect3>
<sect3 id="highlight-system-rules">
<title
>Regras</title>
<para
>As regras de detecção são o "coração" do sistema de detecção de sintaxe. Uma regra é uma string, um caractere ou uma <link linkend="regular-expressions"
>expressão regular</link
> com a qual se faz a correspondência do texto a analisar. Contém informações sobre o estilo a ser usado na parte correspondente do texto. Pode mudar do contexto atual do sistema para outro contexto explícito ou para o contexto anterior usado pelo texto.</para>
<para
>As regras são organizadas em grupos de contexto, sendo que este é usado pelos conceitos principais do texto dentro de um formato, como por exemplo strings dentro de aspas ou blocos de comentário do código-fonte de um programa. Isto garante que o sistema de realce não precisa ficar procurando todas as regras quando não for necessário, e também que sequências de algum caractere no texto podem ser tratadas de modo diferente, dependendo do contexto atual. </para>
<para
>As regras são organizadas em grupos de contexto, sendo que este é usado pelos conceitos principais do texto dentro de um formato, como por exemplo strings dentro de aspas ou blocos de comentário do código-fonte de um programa. Isto garante que o sistema de realce não precisa ficar procurando todas as regras quando não for necessário, e também que sequências de algum caractere no texto podem ser tratadas de modo diferente, dependendo do contexto atual.</para>
</sect3>
<sect3 id="highlight-context-styles-keywords">
<title
>Estilos de Contexto e Palavras-Chave</title>
<para
>Em algumas linguagens de programação, os números inteiros são tratados diferentemente dos números de ponto flutuante pelo compilador (o programa que converte o código-fonte para um binário executável), e podem existir caracteres que possuem significado especial dentro de uma string. Em tais casos, faz sentido renderizá-los de modo diferente dos outros, assim, são mais fáceis de identificar durante a leitura do texto. Mesmo que eles não sejam representados em contextos especiais, pode ser vistos no sistema de realce de sintaxe, e assim, podem ser marcados com uma renderização diferente.</para>
<para
>Uma definição de sintaxe pode conter tantos estilos quanto forem necessários para cobrir os conceitos do formato no qual serão usados.</para>
<para
>Em muitos formatos, existem listas de palavras, que representam um conceito específico; por exemplo, em linguagens de programação, as declaração de controle são um conceito, nomes de tipos de dados outro conceito, e funções pré-integradas na linguagem um terceiro conceito. O Sistema de Realce de Sintaxe do &kappname; pode usar estas listas para detectar e marcar palavras no texto para enfatizar os conceitos dos formatos.</para>
</sect3>
<sect3 id="kate-highlight-system-default-styles">
<title
>Estilos Padrão</title>
<para
>Se você abrir um arquivo de código em C++, um arquivo de &Java; e um documento em <acronym
>HTML</acronym
> no &kappname;, irá ver que, ainda que os formatos sejam diferentes e, por isso, sejam selecionadas palavras diferentes para um tratamento especial, as cores usadas são as mesmas. Isto deve-se ao fato do &kappname; ter uma lista pré-definida de Estilos Padrão, os quais são usados pelas definições de sintaxe individuais.</para>
<para
>Isto faz com que fique mais fácil reconhecer conceitos similares em diferentes formatos. Por exemplo, os comentários estão presentes na maioria das linguagens de programação, script e marcação, e quando são renderizados utilizando-se o mesmo estilo em todas as linguagens, você não precisa parar e pensar para identificá-los dentro do texto.</para>
<tip>
<para
>Todos os estilos de uma definição de sintaxe usam um dos estilos padrão. Algumas definições de sintaxe usam mais estilos além dos pré-definidos, por isso se você usar um formato frequentemente, pode ser útil abrir a janela de configuração para ver se alguns conceitos usam o mesmo estilo. Por exemplo, só existe um estilo padrão para as cadeias de caracteres, mas como a linguagem de programação Perl lida com dois tipos de cadeias de caracteres, você pode melhorar o realce se configurar esses dois tipos de uma forma ligeiramente diferente. Todos os <link linkend="kate-highlight-default-styles"
>estilos padrão disponíveis</link
> serão explicados mais tarde.</para>
</tip>
</sect3>
</sect2>
<sect2 id="katehighlight-xml-format">
<title
>O Formato &XML; de Definição de Realce</title>
<sect3>
<title
>Introdução</title>
<para
>Esta seção é uma introdução ao formato &XML; de Definição de Realce. Baseado em um pequeno exemplo, ele irá descrever as componentes principais, bem como o seu significado e utilização. A próxima seção colocará em detalhes as regras de detecção.</para>
<para
>A definição formal, também conhecida como <acronym
>XSD</acronym
>, é armazenada no arquivo <filename
>language.xsd</filename
>, o qual deve estar instalado na pasta <filename
>$<envar
>XDG_DATA_DIRS</envar
>/katepart5/syntax</filename
> do seu sistema. Nesse sentido, a variável de ambiente <envar
>XDG_DATA_DIRS</envar
> normalmente se expande para <filename
>/usr/share</filename
>. </para>
<variablelist>
<title
>Seções principais dos arquivos de Definições de Realce do &kappname;</title>
<varlistentry>
<term
>Um arquivo de realce contém um cabeçalho que define a versão do XML:</term>
<listitem>
<programlisting
><?xml version="1.0" encoding="UTF-8"?>
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term
>A raiz do arquivo de definição é o elemento <userinput
>language</userinput
>. Os atributos disponíveis são:</term>
<listitem>
<para
>Atributos necessários:</para>
<para
>O <userinput
>name</userinput
> define o nome da linguagem. Ele aparece nos respectivos menus e janelas.</para>
<para
>O <userinput
>section</userinput
> indica a categoria.</para>
<para
>O <userinput
>extensions</userinput
> define as extensões dos arquivos, como por exemplo, "*.cpp;*.h"</para>
<para
>Atributos opcionais:</para>
<para
>O <userinput
>mimetype</userinput
> associa os arquivos do tipo &MIME;.</para>
<para
>O <userinput
>version</userinput
> indica a versão atual do arquivo de definição.</para>
<para
>O <userinput
>kateversion</userinput
> indica a última versão suportada pelo &kappname;.</para>
<para
>O <userinput
>casesensitive</userinput
> define se as palavras-chave fazem distinção entre maiúsculas e minúsculas.</para>
<para
>O <userinput
>priority</userinput
> é necessário se outro arquivo de definições de realce usar as mesmas extensões. Ganhará o que tiver maior prioridade.</para>
<para
>O <userinput
>author</userinput
> contém o nome do autor e o seu endereço de e-mail.</para>
<para
>O <userinput
>license</userinput
> contém a licença, que é normalmente a LGPL, a Artistic, a GPL ou outras.</para>
<para
>O <userinput
>style</userinput
> contém a linguagem fornecida e é usado pelos sistemas de recuo para o atributo <literal
>required-syntax-style</literal
>.</para>
<para
>O <userinput
>hidden</userinput
> define se o nome deverá aparecer nos menus do &kappname;.</para>
<para
>Assim, a próxima linha se parece com o seguinte:</para>
<programlisting
><language name="C++" version="1.00" kateversion="2.4" section="Sources" extensions="*.cpp;*.h" />
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term
>A seguir vem o elemento <userinput
>highlighting</userinput
>, que contém o elemento opcional <userinput
>list</userinput
> e os elementos obrigatórios <userinput
>contexts</userinput
> e <userinput
>itemDatas</userinput
>.</term>
<listitem>
<para
>O elemento <userinput
>list</userinput
> contém uma lista de palavras-chave. Neste caso, as palavras-chave são a <emphasis
>class</emphasis
> e a <emphasis
>const</emphasis
>.Você poderá adicionar tantas listas quanto desejar.</para>
<para
>O elemento <userinput
>contexts</userinput
> contém todos os contextos. O primeiro contexto é, por padrão, o início do realce. Existem duas regras no contexto <emphasis
>Normal Text</emphasis
> (Texto Normal), que correspondem à lista de palavras-chave com o nome <emphasis
>um_nome</emphasis
> e uma regra que detecta aspas e muda o contexto para <emphasis
>string</emphasis
> (cadeia de caracteres). Para aprender mais sobre as regras, leia o próximo capítulo.</para>
<para
>A terceira parte é o elemento <userinput
>itemDatas</userinput
>. Contém todas as cores e estilos de fonte necessários pelos contextos e regras. Neste exemplo, são usados o <userinput
>itemData</userinput
> de <emphasis
>Normal Text</emphasis
> (Texto Normal), <emphasis
>String</emphasis
> (Cadeia de Caracteres) e <emphasis
>Keyword</emphasis
> (Palavra-Chave). </para>
<programlisting
><highlighting>
<list name="um_nome">
<item> class </item>
<item> const </item>
</list>
<contexts>
<context attribute="Normal Text" lineEndContext="#pop" name="Normal Text" >
<keyword attribute="Keyword" context="#stay" String="somename" />
<DetectChar attribute="String" context="string" char="&quot;" />
</context>
<context attribute="String" lineEndContext="#stay" name="string" >
<DetectChar attribute="String" context="#pop" char="&quot;" />
</context>
</contexts>
<itemDatas>
<itemData name="Normal Text" defStyleNum="dsNormal" />
<itemData name="Keyword" defStyleNum="dsKeyword" />
<itemData name="String" defStyleNum="dsString" />
</itemDatas>
</highlighting>
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term
>A última parte de uma definição de realce é a seção opcional <userinput
>general</userinput
>. Ela poderá conter informações sobre as palavras-chave, expansão/recolhimento de código, comentários e recuo.</term>
<listitem>
<para
>A seção <userinput
>comment</userinput
> define com que texto é introduzido um comentário para uma única linha. Você poderá também definir comentários multilinha, usando o <emphasis
>multiLine</emphasis
> com o atributo adicional <emphasis
>end</emphasis
>. Isto é usado se o usuário pressionar o atalho correspondente para <emphasis
>comentar/descomentar</emphasis
>.</para>
<para
>A seção <userinput
>keywords</userinput
> define se as listas de palavras-chave fazem distinção entre maiúsculas e minúsculas ou não. Os outros atributos serão explicados mais tarde.</para>
<programlisting
><general>
<comments>
<comment name="singleLine" start="#"/>
</comments>
<keywords casesensitive="1"/>
</general>
</language>
</programlisting>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="kate-highlight-sections">
<title
>As Seções em Detalhe</title>
<para
>Esta parte irá descrever todos os atributos disponíveis para o 'contexts', o 'itemDatas', o 'keywords', o 'comments', a expansão de código e o recuo.</para>
<variablelist>
<varlistentry>
<term
>O elemento <userinput
>context</userinput
> pertence ao grupo <userinput
>contexts</userinput
>. Um contexto, por si só, define as regras específicas do contexto, como o que deve acontecer se o sistema de realce chegar ao fim de uma linha. Os atributos disponíveis são:</term>
<listitem>
<para
><userinput
>name</userinput
> declara o nome do contexto. As regras irão usar esse nome para indicar o contexto para onde mudar, se a regra corresponder.</para>
<para
>O <userinput
>lineEndContext</userinput
> define o contexto para onde o sistema de realce salta, se atingir o fim de uma linha. Poderá ser o nome de outro contexto, o <userinput
>#stay</userinput
> para não mudar de contexto (⪚, não fazer nada) ou o <userinput
>#pop</userinput
> que fará com que saia deste contexto. É possível usar, por exemplo, <userinput
>#pop#pop#pop</userinput
> para sair de dentro de três contextos, ou ainda <userinput
>#pop#pop!OutroContexto</userinput
> para sair duas vezes e mudar para o contexto <userinput
>OutroContexto</userinput
>.</para>
<para
>O <userinput
>lineEmptyContext</userinput
> define o contexto, se for encontrada uma linha em branco. Padrão: #stay.</para>
<para
>O <userinput
>fallthrough</userinput
> define se o sistema de realce salta para o contexto indicado em 'fallthroughContext' se não corresponder nenhuma regra. Padrão: <emphasis
>false</emphasis
>.</para>
<para
>O <userinput
>fallthroughContext</userinput
> define o próximo contexto, se nenhuma regra corresponder.</para>
<para
>O <userinput
>dynamic</userinput
>, se for <emphasis
>true</emphasis
> (verdadeiro), fará com que o contexto recorde os textos/sequências de substituição gravados pelas regras dinâmicas. Isto é necessário, por exemplo, para os documentos do HERE. Padrão: <emphasis
>false</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>O elemento <userinput
>itemData</userinput
> está no grupo <userinput
>itemDatas</userinput
>. Define o estilo e as cores da fonte. Assim, é possível definir os seus próprios estilos e cores. Contudo, recomenda-se que usar os estilos predefinidos, para que o usuário veja sempre as mesmas cores usadas em várias linguagens. Todavia, existem casos em que não existe outra forma e, assim, é necessário mudar os atributos de cores e tipos de fonte. Os atributos 'name' e 'defStyleNum' são obrigatórios, enquanto os outros são opcionais. Os atributos disponíveis são:</term>
<listitem>
<para
>O <userinput
>name</userinput
> define o nome do 'itemData'. Os contextos e regras irão usar este nome no seu atributo <emphasis
>attribute</emphasis
>, para referenciar um 'itemData'.</para>
<para
>O <userinput
>defStyleNum</userinput
> define qual o estilo padrão usar. Os estilos pré-definidos disponíveis são explicados mais tarde em detalhes.</para>
<para
>O <userinput
>color</userinput
> define uma cor. Os formatos válidos são o '#rrggbb' ou '#rgb'.</para>
<para
>O <userinput
>selColor</userinput
> define a cor da seleção.</para>
<para
>O <userinput
>italic</userinput
>, se for <emphasis
>true</emphasis
> (verdadeiro), irá colocar o texto em itálico.</para>
<para
>O <userinput
>bold</userinput
>, se for <emphasis
>true</emphasis
> (verdadeiro), irá colocar o texto em negrito.</para>
<para
>O <userinput
>underline</userinput
>, se for <emphasis
>true</emphasis
> (verdadeiro), irá colocar o texto sublinhado.</para>
<para
>O <userinput
>strikeout</userinput
>, se for <emphasis
>true</emphasis
> (verdadeiro), o texto ficará traçado.</para>
<para
>O <userinput
>spellChecking</userinput
>, se for <emphasis
>true</emphasis
> (verdadeiro), será verificada a ortografia do texto.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>O elemento <userinput
>keywords</userinput
>, no grupo <userinput
>general</userinput
>, define as propriedades das palavras-chave. Os atributos disponíveis são:</term>
<listitem>
<para
>O <userinput
>casesensitive</userinput
> poderá ser <emphasis
>true</emphasis
> (verdadeiro) ou <emphasis
>false</emphasis
> (falso). Se for <emphasis
>true</emphasis
>, todas as palavras-chave farão distinção entre maiúsculas e minúsculas.</para>
<para
>O <userinput
>weakDeliminator</userinput
> é uma lista de caracteres que não irão atuar como separadores de palavras. Por exemplo, o ponto <userinput
>'.'</userinput
> é um separador de palavras. Assuma que uma palavra-chave num <userinput
>list</userinput
> contém um ponto; nesse caso, só irá corresponder se indicar que o ponto é um delimitador fraco.</para>
<para
>O <userinput
>additionalDeliminator</userinput
> define os delimitadores ou separadores adicionais.</para>
<para
>O <userinput
>wordWrapDeliminator</userinput
> define os caracteres após os quais poderá ocorrer uma mudança de linha.</para>
<para
>Os delimitadores pré-definidos e de mudança de linha são os caracteres <userinput
>.():!+,-<=>%&*/;?[]^{|}~\</userinput
>, o espaço (<userinput
>' '</userinput
>) e a tabulação (<userinput
>'\t'</userinput
>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>O elemento <userinput
>comment</userinput
>, no grupo <userinput
>comments</userinput
>, define as propriedades dos comentários que são usadas nas opções <menuchoice
><guimenu
>Ferramentas</guimenu
><guimenuitem
>Comentar</guimenuitem
></menuchoice
> e <menuchoice
><guimenu
>Ferramentas</guimenu
><guimenuitem
>Descomentar</guimenuitem
></menuchoice
>. Os atributos disponíveis são:</term>
<listitem>
<para
>O <userinput
>name</userinput
> tanto poderá ser <emphasis
>singleLine</emphasis
> como <emphasis
>multiLine</emphasis
>. Se escolher o <emphasis
>multiLine</emphasis
>, serão necessários os atributos <emphasis
>end</emphasis
> e <emphasis
>region</emphasis
>.</para>
<para
>O <userinput
>start</userinput
> define o texto usado para iniciar um comentário. No C++, este será o "/*".</para>
<para
>O <userinput
>end</userinput
> define o texto usado para fechar um comentário. No C++, será o "*/".</para>
<para
>O <userinput
>region</userinput
> deverá ser o nome do comentário multi-linhas que poderá expandir ou recolher. Assuma que tem o <emphasis
>beginRegion="Comment"</emphasis
> ... <emphasis
>endRegion="Comment"</emphasis
> nas suas regras; nesse caso, deverá usar o <emphasis
>region="Comment"</emphasis
>. Desta forma, a remoção de comentários funciona, mesmo que não tenha selecionado todo o texto do comentário multi-linhas. O cursor só precisa estar dentro deste comentário.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>O elemento <userinput
>folding</userinput
>, no grupo <userinput
>general</userinput
>, define as propriedades de dobragem/desdobramento do código. Os atributos disponíveis são:</term>
<listitem>
<para
>O <userinput
>indentationsensitive</userinput
>, se for <emphasis
>true</emphasis
>, aplicará os marcadores de dobragem de código com base no recuo, como acontece na linguagem de programação Python. Normalmente você não terá que definir isto, uma vez que o valor padrão é <emphasis
>false</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>O elemento <userinput
>indentation</userinput
>, no grupo <userinput
>general</userinput
>, define qual o sistema de recuo será usado. Contudo, recomenda-se omitir esse elemento, uma vez que o sistema de recuo será normalmente definido a partir de um Tipo de Arquivo ou através da adição da linha de modo no arquivo de texto. Se você indicar um sistema de recuo, todavia, irá obrigar o usuário a usar um sistema de recuo específico, o que poderá não ser o que ele quer. Os atributos disponíveis são:</term>
<listitem>
<para
>O <userinput
>mode</userinput
> é o nome do sistema de recuo. Os sistemas disponíveis atualmente são: <emphasis
>normal, cstyle, haskell, lilypond, lisp, python, ruby</emphasis
> e <emphasis
>xml</emphasis
>.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="kate-highlight-default-styles">
<title
>Estilos Padrão Disponíveis</title>
<para
>Os estilos padrão <link linkend="kate-highlight-system-default-styles"
>já foram explicados</link
>, em resumo: Os estilos padrão são os estilos de cores e fontes pré-definidos.</para>
<variablelist>
<varlistentry>
<term
>Estilos padrão gerais:</term>
<listitem>
<para
><userinput
>dsNormal</userinput
>, quando não é necessário nenhum realce em especial.</para>
<para
><userinput
>dsKeyword</userinput
>, para as palavras-chave do idioma incorporadas.</para>
<para
><userinput
>dsFunction</userinput
>, nas chamadas e definições de funções.</para>
<para
><userinput
>dsVariable</userinput
>, se aplicável: nomes das variáveis (por exemplo, $algumaVariavel em PHP/Perl).</para>
<para
><userinput
>dsControlFlow</userinput
>, palavras-chave de controle de fluxo, como o 'if', 'else', 'switch', 'break', 'return', 'yield', ...</para>
<para
><userinput
>dsOperator</userinput
>, operadores como o + - * / :: < ></para>
<para
><userinput
>dsBuiltIn</userinput
>, nas funções, classes e objetos incorporados.</para>
<para
><userinput
>dsExtension</userinput
>, extensões comuns, como as classes e funções/macros do Qt em C++ e Python.</para>
<para
><userinput
>dsPreprocessor</userinput
>, para as instruções do pré-processador ou para as definições de macros.</para>
<para
><userinput
>dsAttribute</userinput
>, anotações como o @override e o __declspec(...).</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Estilos padrão relacionados com as strings:</term>
<listitem>
<para
><userinput
>dsChar</userinput
>, para caracteres únicos, como o 'x'.</para>
<para
><userinput
>dsSpecialChar</userinput
>, caracteres com significados especiais nas strings, como as sequências de escape, substituições ou operadores de expressões regulares.</para>
<para
><userinput
>dsString</userinput
>, para strings do tipo "olá mundo".</para>
<para
><userinput
>dsVerbatimString</userinput
>, strings literais como o 'raw \backlash' do Perl, CoffeeScript e das linhas de comando, assim como o r'\raw' do Python.</para>
<para
><userinput
>dsSpecialString</userinput
>, SQL, expressões regulares, documentação, modo matemático do LaTeX, ...</para>
<para
><userinput
>dsImport</userinput
>, importação, inclusão ou requisição de módulos.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Estilos padrão relacionados com números:</term>
<listitem>
<para
><userinput
>dsDataType</userinput
>, para os tipos de dados incorporados, como o 'int', 'void', 'u64'.</para>
<para
><userinput
>dsDecVal</userinput
>, nos valores decimais.</para>
<para
><userinput
>dsBaseN</userinput
>, nos valores com uma base diferente de 10.</para>
<para
><userinput
>dsFloat</userinput
>, nos valores de ponto flutuante.</para>
<para
><userinput
>dsConstant</userinput
>, nas constantes incorporadas e definidas pelo usuário, como o PI.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Estilos padrão de comentários e relacionados com a documentação:</term>
<listitem>
<para
><userinput
>dsComment</userinput
>, para comentários.</para>
<para
><userinput
>dsDocumentation</userinput
>, para /** Comentários de documentação */ ou """strings de documentação""".</para>
<para
><userinput
>dsAnnotation</userinput
>, para os comandos de documentação como o @param, @brief.</para>
<para
><userinput
>dsCommentVar</userinput
>, os nomes das variáveis usadas nos comandos acima, como o "foobar" no @param foobar.</para>
<para
><userinput
>dsRegionMarker</userinput
>, para marcadores de região, como o //BEGIN, //END nos comentários.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Outros estilos padrão:</term>
<listitem>
<para
><userinput
>dsInformation</userinput
>, notas e dicas do tipo @note no doxygen.</para>
<para
><userinput
>dsWarning</userinput
>, para os avisos do tipo @warning no doxygen.</para>
<para
><userinput
>dsAlert</userinput
>, para palavras especiais como o TODO, FIXME, XXXX.</para>
<para
><userinput
>dsError</userinput
>, para realçar erros e sintaxes inválidas.</para>
<para
><userinput
>dsOthers</userinput
>, quando nada mais se aplica.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect2>
<sect2 id="kate-highlight-rules-detailled">
<title
>Regras de Detecção de Realce</title>
<para
>Esta seção descreve as regras de detecção de sintaxe.</para>
<para
>Cada regra pode corresponder a zero ou mais caracteres no início do texto que é testado. Se a regra corresponder, é atribuído o estilo ou <emphasis
>atributo</emphasis
> definido pela regra aos caracteres correspondentes; uma regra poderá perguntar se o contexto atual será alterado.</para>
<para
>As regras se parecem com isto:</para>
<programlisting
><NomeRegra attribute="(identificador)" context="(identifier)" [atributos específicos da regra] /></programlisting>
<para
>O <emphasis
>attribute</emphasis
> identifica o estilo a usar para os caracteres correspondentes pelo nome ou índice; o <emphasis
>context</emphasis
> identifica, como esperado, o contexto a usar a partir daqui.</para>
<para
>O <emphasis
>context</emphasis
> pode ser identificado por:</para>
<itemizedlist>
<listitem>
<para
>Um <emphasis
>identificador</emphasis
>, que é o nome do outro contexto.</para>
</listitem>
<listitem>
<para
>Uma <emphasis
>ordem</emphasis
> diz ao mecanismo para ficar no contexto atual (<userinput
>#stay</userinput
>), ou voltar a usar um contexto usado anteriormente na string (<userinput
>#pop</userinput
>).</para>
<para
>Para voltar mais passos, a palavra-chave #pop pode ser repetida: <userinput
>#pop#pop#pop</userinput
></para>
</listitem>
<listitem>
<para
>Uma <emphasis
>ordem</emphasis
> seguida de um ponto de exclamação (<emphasis
>!</emphasis
>) e um <emphasis
>identificador</emphasis
>, que fará com que o mecanismo siga primeiro a ordem e depois mude para o outro contexto, por exemplo, <userinput
>#pop#pop!OtherContext</userinput
>.</para>
</listitem>
</itemizedlist>
<para
>Algumas regras podem ter <emphasis
>regras-filhas</emphasis
>, as quais podem ser avaliadas se e só se a regra-mãe foi verificada. O texto inteiro verificado terá o atributo definido pela regra-mãe. Uma regra com regras-filhas se pareceria com a seguinte:</para>
<programlisting
><NomedaRegra (atributos)>
<NomedaRegraFilha (atributos) />
...
</NomedaRegra>
</programlisting>
<para
>Os atributos específicos da regra variam e estão descritos nas seções a seguir.</para>
<itemizedlist>
<title
>Atributos comuns</title>
<para
>Todas as regras possuem os seguintes atributos em comum e estão disponíveis sempre que os <userinput
>(atributos comuns)</userinput
> aparecerem. O <emphasis
>attribute</emphasis
> e o <emphasis
>context</emphasis
> são atributos obrigatórios, enquanto os outros são opcionais. </para>
<listitem>
<para
><emphasis
>attribute</emphasis
>: Um atributo mapeia-se para um <emphasis
>itemData</emphasis
> definido.</para>
</listitem>
<listitem>
<para
><emphasis
>context</emphasis
>: Indica o contexto para onde muda o sistema de realce, se a regra corresponder.</para>
</listitem>
<listitem>
<para
><emphasis
>beginRegion</emphasis
>: Inicia um bloco de dobragem de código. Padrão: não definido.</para>
</listitem>
<listitem>
<para
><emphasis
>endRegion</emphasis
>: Fecha uma região de dobragem de código. Padrão: não definido.</para>
</listitem>
<listitem>
<para
><emphasis
>lookAhead</emphasis
>: Se for <emphasis
>true</emphasis
> (verdadeiro), o sistema de realce não irá processar o tamanho da correspondência. Padrão: <emphasis
>false</emphasis
>.</para>
</listitem>
<listitem>
<para
><emphasis
>firstNonSpace</emphasis
>: Corresponder apenas se o texto for o primeiro não-espaço em branco da linha. Padrão: <emphasis
>false</emphasis
>.</para>
</listitem>
<listitem>
<para
><emphasis
>column</emphasis
>: Corresponder apenas se a coluna corresponder. Padrão: não definido.</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title
>Regras dinâmicas</title>
<para
>Algumas regras permitem o atributo opcional <userinput
>dynamic</userinput
>, do tipo booleano, cujo valor padrão é <emphasis
>false</emphasis
>. Se o 'dynamic' for <emphasis
>true</emphasis
>, uma regra poderá usar sequências de substituição que representam o texto correspondente a uma <emphasis
>expressão regular</emphasis
> que mudou para o contexto atual, nos seus atributos <userinput
>string</userinput
> ou <userinput
>char</userinput
>. Num <userinput
>string</userinput
>, o texto de substituição <replaceable
>%N</replaceable
> (em que o N é um número) será substituído pela captura correspondente a <replaceable
>N</replaceable
> na expressão regular de chamada. Num <userinput
>char</userinput
>, a sequência de substituição deverá ser um número <replaceable
>N</replaceable
> que será substituído pelo primeiro caractere da captura <replaceable
>N</replaceable
> da expressão regular de chamada. Sempre que uma regra permitir este atributo, irá conter um <emphasis
>(dinâmico)</emphasis
>.</para>
<listitem>
<para
><emphasis
>dynamic</emphasis
>: poderá ser <emphasis
>(true|false)</emphasis
>.</para>
</listitem>
</itemizedlist>
<sect3 id="highlighting-rules-in-detail">
<title
>As Regras em Detalhes</title>
<variablelist>
<varlistentry>
<term
>DetectChar</term>
<listitem>
<para
>Detecta um caractere específico. Comumente usado, por exemplo, para encontrar o final das strings citadas.</para>
<programlisting
><DetectChar char="(caractere)" (atributos comuns) (dinâmico) /></programlisting>
<para
>O atributo <userinput
>char</userinput
> define o caractere a ser procurado.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Detect2Chars</term>
<listitem>
<para
>Detecta dois caracteres específicos, em uma ordem definida.</para>
<programlisting
><Detect2Chars char="(caractere)" char1="(caractere)" (atributos comuns) (dinâmico) /></programlisting>
<para
>O atributo <userinput
>char</userinput
> define o primeiro caractere a ser procurado, e o atributo <userinput
>char1</userinput
> o segundo.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>AnyChar</term>
<listitem>
<para
>Detecta um caractere de um conjunto de caracteres especificados.</para>
<programlisting
><AnyChar String="(string)" (atributos comuns) /></programlisting>
<para
>O atributo <userinput
>String</userinput
> define o conjunto de caracteres.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>StringDetect</term>
<listitem>
<para
>Detecta uma string exata.</para>
<programlisting
><StringDetect String="(string)" [insensitive="true|false;"] (atributos comuns) (dinâmico) /></programlisting>
<para
>O atributo <userinput
>String</userinput
> define a sequência a encontrar. O atributo <userinput
>insensitive</userinput
> é por padrão <emphasis
>false</emphasis
> e é passado à função de comparação de cadeias de caracteres. Se o valor for <emphasis
>true</emphasis
> a comparação não faz distinção entre maiúsculas e minúsculas.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>WordDetect</term>
<listitem>
<para
>Detecta um texto exato, mas obriga adicionalmente a que esteja rodeado por limites de palavras, como um ponto <userinput
>'.'</userinput
> ou um espaço em branco no início e no fim da palavra. Pense em <userinput
>\b<texto>\b</userinput
> em termos de uma expressão regular, só que é mais rápido que a regra <userinput
>Exp Reg</userinput
>.</para>
<programlisting
><WordDetect String="(string)" [insensitive="true|false;"] (atributos comuns) (dinâmico) /></programlisting>
<para
>O atributo <userinput
>String</userinput
> define a sequência a encontrar. O atributo <userinput
>insensitive</userinput
> é por padrão <emphasis
>false</emphasis
> e é passado à função de comparação de cadeias de caracteres. Se o valor for <emphasis
>true</emphasis
> a comparação não faz distinção entre maiúsculas e minúsculas.</para>
<para
>Desde: Kate 3.5 (KDE 4.5)</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>RegExpr</term>
<listitem>
<para
>Procura por uma expressão regular.</para>
<programlisting
><RegExpr String="(texto)" [insensitive="true|false"] [minimal="true|false"] (atributos comuns) (dinâmico) /></programlisting>
<para
>O atributo <userinput
>String</userinput
> define a expressão regular.</para>
<para
>O <userinput
>insensitive</userinput
> é, por padrão, <emphasis
>false</emphasis
> e é passado ao motor de expressões regulares.</para>
<para
>O <userinput
>minimal</userinput
> é, por padrão, <emphasis
>false</emphasis
> e é passado ao motor de expressões regulares.</para>
<para
>Pelo motivo que as regras estão sempre iniciando a busca no início da string atual, uma expressão regular iniciada com um acento circunflexo (<literal
>^ </literal
>) indica que a regra deve ser coincidente somente no início da linha.</para>
<para
>Veja em <link linkend="regular-expressions"
>Expressões Regulares</link
> mais informações sobre o assunto.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>keyword</term>
<listitem>
<para
>Detecta uma palavra-chave de uma lista especificada.</para>
<programlisting
><keyword String="(nome da lista)" (atributos comuns) /></programlisting>
<para
>O atributo <userinput
>String</userinput
> identifica a lista de palavras-chave pelo nome. Uma lista com aquele nome, portanto, deve existir.</para>
<para
>O sistema de realce processa as regras da palavra-chave de forma muito otimizada. Isto a torna uma necessidade absoluta em que quaisquer palavras-chave a corresponder sejam envolvidas por separadores definidos, sejam eles implícitos (os separadores padrão) ou explícitos, com a propriedade <emphasis
>additionalDeliminator</emphasis
> da marca <emphasis
>keywords</emphasis
>.</para>
<para
>Se uma palavra-chave a corresponder conter um caractere separador, este caractere respectivo deverá ser adicionado à propriedade <emphasis
>weakDeliminator</emphasis
> da marca <emphasis
>keywords</emphasis
>. Este caractere irá então perder a sua propriedade de separador em todas as regras <emphasis
>keyword</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Int</term>
<listitem>
<para
>Detecta um número inteiro.</para>
<para
><programlisting
><Int (atributos comuns) (dinâmico) /></programlisting
></para>
<para
>Esta regra não tem atributos específicos. As regras-filho são tipicamente usadas para detectar as combinações de <userinput
>L</userinput
> e <userinput
>U</userinput
> depois do número, o que indica o tipo inteiro no código do programa. De fato, todas as regras são permitidas como regras-filhas, contudo, o <acronym
>DTD</acronym
> só permite a regra-filha <userinput
>StringDetect</userinput
>.</para>
<para
>O exemplo a seguir faz correspondência com os números inteiros, seguidos do caractere 'L'. <programlisting
><Int attribute="Decimal" context="#stay" >
<StringDetect attribute="Decimal" context="#stay" String="L" insensitive="true"/>
</Int>
</programlisting
></para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Float</term>
<listitem>
<para
>Detecta um número de ponto flutuante.</para>
<para
><programlisting
><Float (atributos comuns) /></programlisting
></para>
<para
>Esta regra não tem atributos específicos. O <userinput
>AnyChar</userinput
> é permitido como regra-filha e é tipicamente usada para detectar combinações; veja a regra <userinput
>Int</userinput
> para mais referências.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCOct</term>
<listitem>
<para
>Detecta uma representação de um número octal.</para>
<para
><programlisting
><HlCOct (atributos comuns) /></programlisting
></para>
<para
>Esta regra não possui atributos específicos.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCHex</term>
<listitem>
<para
>Detecta uma representação de um número hexadecimal.</para>
<para
><programlisting
><HlCHex (atributos comuns) /></programlisting
></para>
<para
>Esta regra não possui atributos específicos.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCStringChar</term>
<listitem>
<para
>Detecta um caractere de escape.</para>
<para
><programlisting
><HlCStringChar (atributos comuns) /></programlisting
></para>
<para
>Esta regra não possui atributos específicos.</para>
<para
>Corresponde a representações literais dos caracteres usados normalmente no código do programa como, por exemplo, o <userinput
>\n</userinput
> (nova linha) ou o <userinput
>\t</userinput
> (TAB).</para>
<para
>Os seguintes caracteres irão corresponder se estiverem após uma barra invertida (<literal
>\</literal
>): <userinput
>abefnrtv"'?\</userinput
>. Além disso, os números escapados em hexadecimal como, por exemplo, o <userinput
>\xff</userinput
> e os números octais escapados, como o <userinput
>\033</userinput
>, irão corresponder.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCChar</term>
<listitem>
<para
>Detecta um caractere do C.</para>
<para
><programlisting
><HlCChar (atributos comuns) /></programlisting
></para>
<para
>Esta regra não possui atributos específicos.</para>
<para
>Corresponde aos caracteres em C colocados dentro de um tique (Exemplo: <userinput
>'c'</userinput
>). Os tiques podem ser um único caractere ou um caractere de escape. Veja o 'HlCStringChar' para ver as sequências de caracteres de escape correspondentes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>RangeDetect</term>
<listitem>
<para
>Detecta uma string com os caracteres de início e fim definidos.</para>
<programlisting
><RangeDetect char="(caractere)" char1="(caractere)" (atributos comuns) /></programlisting>
<para
>O <userinput
>char</userinput
> define o caractere de início e o <userinput
>char1</userinput
> o caractere que termina o intervalo.</para>
<para
>Útil para detectar, por exemplo, pequenas cadeias de caracteres entre aspas e semelhantes, mas repare que, uma vez que o motor de realce de sintaxe funciona com uma linha de cada vez, isto não irá encontrar as cadeias de caracteres que se prolonguem por mais de uma linha.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>LineContinue</term>
<listitem>
<para
>Corresponde um caractere específico indicado no fim de uma linha.</para>
<programlisting
><LineContinue (atributos comuns) [char="\"] /></programlisting>
<para
>O atributo <userinput
>char</userinput
> define o caractere opcional a ser encontrado, sendo a barra invertida (<userinput
>'\'</userinput
>). o padrão. Novidade da versão 4.13 do &kde;.</para>
<para
>Esta regra é útil para mudar de contexto no fim da linha. Isso é necessário no C/C++, por exemplo, para continuar as macros ou cadeias de caracteres.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>IncludeRules</term>
<listitem>
<para
>Inclui as regras de outro contexto ou linguagem/arquivo.</para>
<programlisting
><IncludeRules context="ligacao_contexto" [includeAttrib="true|false"] /></programlisting>
<para
>O atributo <userinput
>context</userinput
> define o contexto a incluir.</para>
<para
>Se for texto simples, inclui todas as regras definidas no contexto atual, como por exemplo: <programlisting
><IncludeRules context="outroContexto" /></programlisting
></para>
<para
>Se o texto conter um <userinput
>##</userinput
>, o sistema de realce irá procurar por um contexto de outra definição de linguagem com o nome indicado, por exemplo, <programlisting
><IncludeRules context="String##C++" /></programlisting
> iria incluir o contexto <emphasis
>String</emphasis
> da definição de realce <emphasis
>C++</emphasis
>.</para>
<para
>Se o atributo <userinput
>includeAttrib</userinput
> for <emphasis
>true</emphasis
>, muda o atributo de destino para o da origem. Isto é necessário para fazer, por exemplo, funcionar os comentários, se o texto correspondente ao contexto incluído for de um realce diferente do contexto-anfitrião. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
>DetectSpaces</term>
<listitem>
<para
>Detecta espaços em branco.</para>
<programlisting
><DetectSpaces (atributos comuns) /></programlisting>
<para
>Esta regra não possui atributos específicos.</para>
<para
>Use esta regra se souber que poderão existir vários espaços em branco à frente como, por exemplo, no início das linhas recuadas. Esta regra irá ignorar todos os espaços em branco, em vez de testar várias regras e ignorar uma de cada vez, devido a uma falta de correspondência.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>DetectIdentifier</term>
<listitem>
<para
>Detecta os textos dos identificadores (como acontece na expressão regular: [a-zA-Z_][a-zA-Z0-9_]*).</para>
<programlisting
><DetectIdentifier (atributos comuns) /></programlisting>
<para
>Esta regra não possui atributos específicos.</para>
<para
>Use esta regra para ignorar uma sequência de caracteres de palavras de uma vez, em vez de testar com várias regras e ignorar uma de cada vez, por falta de correspondência.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title
>Dicas & Truques</title>
<itemizedlist>
<para
>Logo que tenha compreendido como funciona a mudança de contexto, será fácil de criar definições de realce. Ainda que você deva verificar com cuidado a regra que escolher, dependendo da situação, as expressões regulares são muito poderosas, só que são lentas em comparação com as outras regras. Assim, você poderá considerar útil as seguintes dicas. </para>
<listitem>
<para
>Se você só corresponder com 2 caracteres, use o <userinput
>Detect2Chars</userinput
> em vez do <userinput
>StringDetect</userinput
>. O mesmo aplica-se ao <userinput
>DetectChar</userinput
>.</para>
</listitem>
<listitem>
<para
>As expressões regulares são fáceis de usar mas, normalmente, existe outra forma muito mais rápida de obter o mesmo resultado. Assuma que só deseja corresponder com o caractere <userinput
>'#'</userinput
> se for o primeiro caractere da linha. Uma solução baseada em expressões regulares seria semelhante à seguinte: <programlisting
><RegExpr attribute="Macro" context="macro" String="^\s*#" /></programlisting
> Você poderá obter o mesmo se usar: <programlisting
><DetectChar attribute="Macro" context="macro" char="#" firstNonSpace="true" /></programlisting
> Se quiser corresponder à expressão regular <userinput
>'^#'</userinput
>, poderá usar ainda o <userinput
>DetectChar</userinput
> com o atributo <userinput
>column="0"</userinput
>. O atributo <userinput
>column</userinput
> conta como caracteres; assim, uma tabulação conta como se fosse apenas um caractere. </para>
</listitem>
<listitem>
<para
>Você poderá mudar de contextos sem processar os caracteres. Assuma que deseja mudar de contexto quando encontrar o texto <userinput
>*/</userinput
>, mas necessita de processar essa sequência no próximo contexto. A regra abaixo irá corresponder e o atributo <userinput
>lookAhead</userinput
> fará com que o sistema de realce mantenha o texto correspondente no próximo contexto. <programlisting
><Detect2Chars attribute="Comment" context="#pop" char="*" char1="/" lookAhead="true" /></programlisting>
</para>
</listitem>
<listitem>
<para
>Use o <userinput
>DetectSpaces</userinput
> se você souber que irão ocorrer vários espaços em branco.</para>
</listitem>
<listitem>
<para
>Use o <userinput
>DetectIdentifier</userinput
> em vez da expressão regular <userinput
>'[a-zA-Z_]\w*'</userinput
>.</para>
</listitem>
<listitem>
<para
>Use os estilos padrão sempre que puder. Desta forma, o usuário irá encontrar um ambiente familiar.</para>
</listitem>
<listitem>
<para
>Procure em outros arquivos XML para ver como as outras pessoas implementam as regras mais complicadas.</para>
</listitem>
<listitem>
<para
>Você poderá validar todos os arquivos XML se usar o comando <command
>xmllint --schema language.xsd MinhaSintaxe.xml</command
>.</para>
</listitem>
<listitem>
<para
>Se repetir algumas expressões regulares complexas com frequência, você poderá usar as <emphasis
>ENTIDADES</emphasis
>. Por exemplo:</para>
<programlisting
><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE language SYSTEM "language.dtd"
[
<!ENTITY referencia "[A-Za-z_:][\w.:_-]*">
]>
</programlisting>
<para
>Agora, você poderá usar o <emphasis
>&referencia;</emphasis
> em vez da expressão regular.</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="dev-scripting">
<title
>Criação de scripts com JavaScript</title>
<para
>O componente de edição do &kappname; é facilmente extensível, através da criação de scripts. A linguagem de programação é o ECMAScript (popularmente conhecido como JavaScript). O &kappname; suporta dois tipos de scripts: os de recuo e os de linha de comando. </para>
<sect2 id="dev-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 a tecla 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 de, ⪚, <filename
>javascript.js</filename
> na pasta pessoal local <filename
>$<envar
>XDG_DATA_HOME</envar
>/katepart5/script/indentation</filename
>. Nesse sentido, a variável de ambiente <envar
>XDG_DATA_HOME</envar
> normalmente se expande para qualquer <filename
>~/.local</filename
> ou <filename
>~/.local/share</filename
>. </para>
<sect3 id="dev-scripting-indentation-header">
<title
>O cabeçalho do script de recuo</title>
<para
>O cabeçalho do arquivo <filename
>javascript.js</filename
> está incorporado como JSON no início do documento no seguinte formato: <programlisting>
var katescript = {
"name": "JavaScript",
"author": "Nome de Exemplo <nome.exemplo@endereco.org>",
"license": "BSD License",
"revision": 1,
"kate-version": "5.1",
"required-syntax-style": "javascript",
"indent-languages": ["javascript"],
"priority": 0,
}; // kate-script-header, deve estar no início do arquivo, sem comentários
</programlisting
> Cada item será agora explicado em detalhes: <itemizedlist>
<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 License 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]: O estilo do sintaxe necessário, que corresponde ao <literal
>style</literal
> indicado no sintaxe dos arquivos realçados. 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 JSON de estilos de sintaxe que este módulo consegue recuar corretamente, ⪚: <literal
>["c++", "java"]</literal
>. </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>
</sect3>
<sect3 id="dev-scripting-indentation-body">
<title
>O código-fonte do recuador</title>
<para
>Tendo definido o cabeçalho, esta seção explica como funciona a programação de recuadores em si. O esqueleto básico do código parece-se com o seguinte: <programlisting>
// Necessário para as bibliotecas js do katepart, p.ex., range.js se você usar Range
require ("range.js");
caracteresAtivacao = "{}/:;";
function indent(linha, larguraRecuo, caractere)
{
// invocado para cada linha nova (caractere == '\n') e todos os caracteres indicados na
// variável global 'caracteresAtivacao'. Ao invocar o <menuchoice
><guimenu
>Ferramentas</guimenu
><guimenuitem
>Alinhar</guimenuitem
></menuchoice>
// a variável 'caractere' está em branco, isto é, 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 >= 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 <tab> representa uma tabulação e o '.' representa um espaço: <programlisting>
1: <tab><tab>xpto("olá",
2: <tab><tab>......."mundo");
</programlisting
> Ao recuar a linha 2, a função <function
>indent()</function
> devolve [8, 15]. Em função disso, são introduzidas duas tabulações para recuar até à coluna 8, e são introduzidos 7 espaços para alinhar o segundo parâmetro com o primeiro, de modo a permanecer alinhado, caso o arquivo seja visto com outro tamanho de tabulação. </para>
<para
>Uma instalação padrão do &kde; fornece o &kappname; com vários módulos de recuo. O código-fonte correspondente em JavaScript poderá ser encontrado em <filename
>$<envar
>XDG_DATA_DIRS</envar
>/katepart5/script/indentation</filename
>. </para>
<para
>A criação de um módulo de recuo necessita do recarregamento dos scripts, de modo a ver se as alterações se comportam de forma adequada. Em vez de reiniciar o aplicativo, basta ir para a linha de comando e executar o comando <command
>reload-scripts</command
>. </para>
<para
>Se você criar scripts úteis, considere a hipótese de contribuir com eles para o Projeto &kappname;, <ulink url="mailto:kwrite-devel@kde.org"
>contactando para isso a lista de correio</ulink
>. </para>
</sect3>
</sect2>
<sect2 id="dev-scripting-command-line">
<title
>Scripts de Linha de Comando</title>
<para
>Como é difícil satisfazer as necessidades de todos, o &kappname; tem suporte a 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 script. Esta seção explica como criar arquivos <filename
>*.js</filename
> que estendem o &kappname; com algumas funções auxiliares arbitrárias. </para>
<para
>Os scripts de linha de comando estão localizados na mesma pasta que os scripts de recuo. Assim, como primeiro passo, crie um arquivo <filename
>*.js</filename
> novo, chamado <filename
>utilitários.js</filename
> na pasta pessoal local, em <filename
>$<envar
>XDG_DATA_HOME</envar
>/katepart5/script/commands</filename
>. Nesse sentido, a variável de ambiente <envar
>XDG_DATA_HOME</envar
> normalmente se expande para <filename
>~/.local</filename
> ou <filename
>~/.local/share</filename
>. </para>
<sect3 id="dev-scripting-command-line-header">
<title
>O Cabeçalho do Script de Linha de Comando</title>
<para
>O cabeçalho de cada script de linha de comando é está incorporado como JSON no início do script no seguinte formato: <programlisting>
var katescript = {
"author": "Nome de exemplo <nome.exemplo@endereco.org>",
"license": "LGPLv2+",
"revision": 1,
"kate-version": "5.1",
"functions": ["ordenar", "descerLinhas"],
"actions": [
{ "function": "ordenar",
"name": "Ordena o texto selecionado",
"category": "Edição",
"interactive": "false"
},
{ "function": "descerLinhas",
"name": "Desce as linhas",
"category": "Edição",
"shortcut": "Ctrl+Shift+Down",
"interactive": "false"
}
]
}; // kate-script-header, deve estar no início do arquivo, sem comentários
</programlisting
> Cada item será agora explicado em detalhes: <itemizedlist>
<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 License ou LGPLv2.</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 JSON dos comandos do script.</para
></listitem>
<listitem
><para
><literal
>actions</literal
> [opcional]: Lista em JSON de objetos JSON que definem as ações que aparecem no menu do aplicativo. São oferecidas informações detalhadas na seção <link linkend="advanced-editing-tools-commandline"
>Associar combinações de teclas</link
>.</para
></listitem>
</itemizedlist>
</para>
<para
>Uma vez que o valor de <literal
>functions</literal
> é uma lista em JSON, um único script é capaz de conter um número arbitrário de comandos da linha de comando. Cada função está disponível através da <link linkend="advanced-editing-tools-commandline"
>linha de comando incorporada</link
> do &kappname;. </para>
</sect3>
<sect3 id="dev-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
>descerLinhas</command
>. Todas as funções têm a seguinte sintaxe: <programlisting
>// bibliotecas necessárias do katepart js, p.ex., range.js se você usar Range
function <nome>(arg1, arg2, ...)
{
// ... implementação, ver também: API de Programação
}
</programlisting>
</para>
<para
>Os argumentos na linha de comando são passados à função como <parameter
>arg1</parameter
>, <parameter
>arg2</parameter
>, etc. Para poder indicar a documentação de cada comando, basta implementar a função '<function
>help</function
>', como demonstrado a seguir: <programlisting>
function help(cmd)
{
if (cmd == "sort") {
return i18n("Ordena o texto selecionado.");
} else if (cmd == "...") {
// ...
}
}
</programlisting
> Executar <command
>help sort</command
> na linha de comando, irá invocar esta função de ajuda com o argumento <parameter
>cmd</parameter
> igual ao comando indicado, como &ie;, <parameter
>cmd == "sort"</parameter
>. O &kappname; irá assim apresentar o texto devolvido como documentação ao usuário. Certifique-se de <link linkend="dev-scripting-api-i18n"
>traduzir os textos</link
>. </para>
<para
>Criar um script para a linha de comando requer o recarregamento dos scripts, de modo a ver se as alterações funcionam apropriadamente. Em vez de reiniciar o aplicativo, basta mudar para a linha de comando e executar o comando <command
>reload-scripts</command
>. </para>
<sect4 id="dev-scripting-command-line-shortcuts">
<title
>Associar combinações de teclas</title>
<para
>Para tornar os scripts acessíveis no menu do aplicativo e atribuir teclas de atalho, o script precisa fornecer um cabeçalho do script apropriado. No exemplo acima, ambas as funções <literal
>ordenar</literal
> e <literal
>descerLinhas</literal
> aparecem no menu, graças ao seguinte componente no cabeçalho do script: <programlisting>
var katescript = {
...
"actions": [
{ "function": "ordenar",
"name": "Ordena o texto selecionado",
"icon": "",
"category": "Edição",
"interactive": "false"
},
{ "function": "descerLinhas",
"name": "Desce as linhas",
"icon": "",
"category": "Edição",
"shortcut": "Ctrl+Shift+Down",
"interactive": "false"
}
]
};
</programlisting
> Os campos de uma ação são os seguintes: <itemizedlist>
<listitem
><para
><literal
>function</literal
> [obrigatório]: A função que deverá aparecer no menu <menuchoice
><guimenu
>Ferramentas</guimenu
><guisubmenu
>Scripts</guisubmenu
></menuchoice
>.</para
></listitem>
<listitem
><para
><literal
>name</literal
> [obrigatório]: O texto que aparece no menu do script.</para
></listitem>
<listitem
><para
><literal
>icon</literal
> [opcional]: O ícone aparece após ao texto no menu. Todos os nomes de ícones do &kde; poderão ser usados aqui.</para
></listitem>
<listitem
><para
><literal
>category</literal
> [opcional]: Se for indicada uma categoria, o programa aparece num submenu.</para
></listitem>
<listitem
><para
><literal
>shortcut</literal
> [opcional]: A combinação de teclas indicada aqui é o atalho de teclado padrão. Por exemplo: <literal
>Ctrl+Alt+T</literal
>. Veja a <ulink url="http://qt-project.org/doc/qt-5/qt.html#Key-enum"
>documentação do Qt</ulink
> para mais detalhes.</para
></listitem>
<listitem
><para
><literal
>interactive</literal
> [opcional]: Se o script precisa de interação por parte do usuário na linha de comando, configure este valor como <literal
>true</literal
> (verdadeiro).</para
></listitem>
</itemizedlist>
</para>
<para
>Se você criar scripts úteis, considere a hipótese de contribuir com eles para o Projeto &kappname;, <ulink url="mailto:kwrite-devel@kde.org"
>contactando para isso a lista de correio</ulink
>. </para>
</sect4>
</sect3>
</sect2>
<sect2 id="dev-scripting-api">
<title
>API de Programação</title>
<para
>A API de criação de scripts aqui apresentada está disponível em todos os scripts, &ie;, os scripts de recuo e os comandos do terminal. As classes <classname
>Cursor</classname
> e o <classname
>Range</classname
> são fornecidas por arquivos de bibliotecas em <filename
>$<envar
>XDG_DATA_DIRS</envar
>/katepart5/libraries</filename
>. Elas serão necessárias, caso queira usar algumas das funções <classname
>Document</classname
> ou <classname
>View</classname
> no seu script. Inclua a biblioteca necessária usando: <programlisting
>// bibliotecas necessárias do katepart js, p.ex., range.js se você usar Range
require ("range.js");
</programlisting>
</para>
<para
>Para ampliar a API padrão de scripts com suas funções e protótipos próprios, basta criar um arquivo novo na pasta de configuração local do &kde;, em <filename
>$<envar
>XDG_DATA_HOME</envar
>/katepart5/libraries</filename
> e incluí-lo no seu script usando: <programlisting
>require ("myscriptnamehere.js");
</programlisting>
</para>
<para
>Para estender os protótipos existentes, como o <classname
>Cursor</classname
> ou o <classname
>Range</classname
>, a forma recomendada é <emphasis
>não</emphasis
> modificar os arquivos <filename
>*.js</filename
> globais. Em vez disso, altere o protótipo do <filename
>cursor.js</filename
> em JavaScript, após o <filename
>cursor.js</filename
> que é incluído no seu script através do <literal
>require</literal
>. </para>
<sect3 id="dev-scripting-api-prototypes">
<title
>Cursores e Intervalos</title>
<para
>Como o &kappname; é um editor de texto, sempre que possível, toda a API de criação de scripts é baseada em cursores e intervalos. Um cursor é uma simples dupla <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 detalhes nas seções a seguir. </para>
<sect4 id="dev-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
>Cursor.setPosition(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Configura a posição do cursor em <replaceable
>linha</replaceable
> e <replaceable
>coluna</replaceable
>.</para>
<para
>Desde: &kde; 4.11 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Cursor.isValid();
</synopsis
></term>
<listitem
><para
>Verifica se o cursor é válido. O cursor é inválido no caso em que a linha e/ou coluna sejam iguais a <literal
>-1</literal
>. </para>
<para
>Exemplo: <function
>var valido = cursor.isValid();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor Cursor.invalid();
</synopsis
></term>
<listitem
><para
>Devolve um novo cursor inválido, localizado em <literal
>(-1, -1)</literal
>. </para>
<para
>Exemplo: <function
>var cursorInvalido = cursor.invalid();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int Cursor.compareTo(<parameter
>Cursor <replaceable
>outro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Compara este cursor com o cursor <replaceable
>outro</replaceable
>. Devolve <itemizedlist>
<listitem
><para
><literal
>-1</literal
>, se este cursor for localizado antes do cursor <replaceable
>outro</replaceable
>,</para
></listitem>
<listitem
><para
><literal
>0</literal
>, se ambos os cursores forem iguais e</para
></listitem>
<listitem
><para
><literal
>+1</literal
>, se este cursor se localizar após o cursor <replaceable
>outro</replaceable
>.</para
></listitem>
</itemizedlist>
</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Cursor.equals(<parameter
>Cursor <replaceable
>outro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se este o cursor e o <replaceable
>outro</replaceable
> forem iguais, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String Cursor.toString();
</synopsis
></term>
<listitem
><para
>Devolve o cursor como um texto no formato <quote
><literal
>Cursor(linha, coluna)</literal
></quote
>. </para
></listitem>
</varlistentry
></variablelist>
</sect4>
<sect4 id="dev-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.isEmpty();
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se o cursor de início e de fim forem iguais. </para>
<para
>Exemplo: <function
>var vazio = intervalo.isEmpty();</function
> </para>
<para
>Desde: &kde; 4.11 </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
>Range Range.invalid();
</synopsis
></term>
<listitem
><para
>Devolve o intervalo Range de (-1, -1) até (-1, -1). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.contains(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se este intervalo contiver a posição do cursor, caso contrário, devolve <literal
>false</literal
> (falso). </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 semiaberto <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 semiaberto <literal
>[início.linha, fim.linha)</literal
>, caso contrário, devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.overlaps(<parameter
>Range <replaceable
>outro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se este intervalo e o intervalo <replaceable
>outro</replaceable
> compartilharem uma região em comum, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.overlapsLine(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se a <replaceable
>linha</replaceable
> estiver no intervalo <literal
>[início.linha, fim.linha]</literal
>, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.overlapsColumn(<parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se a <replaceable
>coluna</replaceable
> estiver no intervalo <literal
>[início.coluna, fim.coluna]</literal
>, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.onSingleLine();
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se o intervalo inicia e termina na mesma linha, &ie;, se <replaceable
>Range.start.line == Range.end.line</replaceable
>. </para>
<para
>Desde: &kde; 4.9 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.equals(<parameter
>Range <replaceable
>outro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se este intervalo e o intervalo <replaceable
>outro</replaceable
> forem iguais, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String Range.toString();
</synopsis
></term>
<listitem
><para
>Devolve o intervalo como uma string no formato <quote
><literal
>Range(Cursor(linha, coluna), Cursor(linha, coluna))</literal
></quote
>. </para
></listitem>
</varlistentry
></variablelist>
</sect4>
</sect3>
<sect3 id="dev-scripting-api-global">
<title
>Funções globais</title>
<para
>Esta seção apresenta todas as funções globais.</para>
<sect4 id="dev-scripting-api-includes">
<title
>Arquivos de leitura e inclusão</title>
<variablelist
><varlistentry>
<term
><synopsis
>String read(<parameter
>String <replaceable
>arquivo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Irá procurar pelo <replaceable
>arquivo</replaceable
> indicado em relação à pasta <literal
>katepart/script/files</literal
> e irá devolver o seu conteúdo como texto. </para
></listitem>
</varlistentry
></variablelist>
<variablelist
><varlistentry>
<term
><synopsis
>void require(<parameter
>String <replaceable
>Arquivo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Irá procurar pelo <replaceable
>arquivo</replaceable
> indicado em relação à pasta <literal
>katepart/script/libraries</literal
> e avaliá-lo. O <literal
>require</literal
> está protegido internamente contra inclusões múltiplas do mesmo <replaceable
>arquivos</replaceable
>. </para>
<para
>Desde: &kde; 4.10 </para>
</listitem>
</varlistentry
></variablelist>
</sect4>
<sect4 id="dev-scripting-api-debug">
<title
>Depuração</title>
<variablelist
><varlistentry>
<term
><synopsis
>void debug(<parameter
>String <replaceable
>texto</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Imprime o <replaceable
>texto</replaceable
> no <literal
>stdout</literal
>, mais precisamente no console que lança a aplicação. </para
></listitem>
</varlistentry
></variablelist>
</sect4>
<sect4 id="dev-scripting-api-i18n">
<title
>Tradução</title>
<para
>Para um suporte regional completo, existem diversas funções para traduzir os textos nos programas, nomeadamente o <literal
>i18n</literal
>, o <literal
>i18nc</literal
>, o <literal
>i18np</literal
> e o <literal
>i18ncp</literal
>. Estas funções comportam-se exatamente como as <ulink url="http://techbase.kde.org/Development/Tutorials/Localization/i18n"
> funções de tradução do &kde;</ulink
>. </para>
<para
>As funções de tradução convertem os textos indicados ao sistema de traduções do &kde; para o idioma usado no aplicativo. Os textos nos scripts que são desenvolvidos no âmbito do código oficial do &kappname; são automaticamente extraídos e preparados para tradução. Em outras palavras, como desenvolvedor do &kappname;, você não precisa que se preocupar com a extração e tradução. Contudo, a tradução só funciona dentro da infraestrutura do &kde;, &ie;, novos textos em scripts de terceiros, desenvolvidos fora do &kde;, não são traduzidos. Dessa forma, considere contribuir com seus scripts para o &kate;, para que seja possível obter uma tradução adequada. </para>
<variablelist
><varlistentry>
<term
><synopsis
>void i18n(<parameter
>String <replaceable
>texto</replaceable
></parameter
>, <replaceable
>arg1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Traduz o <replaceable
>texto</replaceable
> na língua usada pela aplicação. Os argumentos <replaceable
>arg1</replaceable
>, ..., são opcionais e usados para substituir os itens <literal
>%1</literal
>, <literal
>%2</literal
>, etc.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void i18nc(<parameter
>String <replaceable
>contexto</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>, <replaceable
>arg1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Traduz o <replaceable
>texto</replaceable
> na língua usada pela aplicação. Além disso, o texto do <replaceable
>contexto</replaceable
> fica visível aos tradutores para que possam dar uma tradução mais adequada. Os argumentos <replaceable
>arg1</replaceable
>, ..., são opcionais e são usados para substituir os itens de substituição <literal
>%1</literal
>, <literal
>%2</literal
>, etc.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void i18np(<parameter
>String <replaceable
>singular</replaceable
></parameter
>, <parameter
>String <replaceable
>plural</replaceable
></parameter
>, <parameter
>int <replaceable
>número</replaceable
></parameter
>, <replaceable
>arg1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Traduz tanto o texto <replaceable
>singular</replaceable
> como o <replaceable
>plural</replaceable
> para a língua usada pela aplicação, dependendo do <replaceable
>número</replaceable
> indicado. Os argumentos <replaceable
>arg1</replaceable
>, ..., são opcionais e usados para substituir os itens de substituição <literal
>%1</literal
>, <literal
>%2</literal
>, etc.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void i18ncp(<parameter
>String <replaceable
>contexto</replaceable
></parameter
>, <parameter
>String <replaceable
>singular</replaceable
></parameter
>, <parameter
>String <replaceable
>plural</replaceable
></parameter
>, <parameter
>int<replaceable
>número</replaceable
></parameter
>, <replaceable
>arg1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Traduz tanto o texto <replaceable
>singular</replaceable
> como o <replaceable
>plural</replaceable
> para a língua usada pela aplicação, dependendo do <replaceable
>número</replaceable
> indicado. Adicionalmente, o texto do <replaceable
>contexto</replaceable
> é visível para as tradutores, para que possam fornecer uma tradução mais adequada. Os argumentos <replaceable
>arg1</replaceable
>, ..., são opcionais e são usados para substituir os itens <literal
>%1</literal
>, <literal
>%2</literal
>, etc.</para
></listitem>
</varlistentry
></variablelist>
</sect4>
</sect3>
<sect3 id="dev-scripting-api-view">
<title
>A API do View</title>
<para
>Sempre que um programa está sendo executado, existe uma variável global <quote
><literal
>view</literal
></quote
> que representa a área de edição ativa no momento. Segue-se uma lista com todas as funções disponíveis para o View. <variablelist
><varlistentry>
<term
><synopsis
><function
>Cursor view.cursorPosition()</function
>
</synopsis
></term>
<listitem
><para
>Devolve a posição atual do cursor na janela.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.setCursorPosition(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
void view.setCursorPosition(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Altera a posição atual do cursor para uma (linha, coluna) qualquer ou para o cursor indicado. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor view.virtualCursorPosition();
</synopsis
></term>
<listitem
><para
>Devolve a posição virtual do cursor com cada tabulação a corresponder ao número indicado de espaços, dependente da largura de tabulação atual. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.setVirtualCursorPosition(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
void view.setVirtualCursorPosition(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Altera a posição atual do cursor virtual para uma (linha, coluna) qualquer ou para o cursor indicado. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String view.selectedText();
</synopsis
></term>
<listitem
><para
>Devolve o texto selecionado. Se não tiver nenhum texto selecionado, o texto devolvido vem vazio. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool view.hasSelection();
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se a janela contiver algum texto selecionado, caso contrário, devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range view.selection();
</synopsis
></term>
<listitem
><para
>Devolve o intervalo de texto selecionado. O intervalo devolvido é inválido, caso não esteja selecionado nenhum texto. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.setSelection(<parameter
>Range <replaceable
>intervalo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Altera o texto selecionado para o intervalo indicado. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.removeSelectedText();
</synopsis
></term>
<listitem
><para
>Remove o texto selecionado. Se a janela não tiver nenhuma seleção feita, isto não faz nada. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.selectAll();
</synopsis
></term>
<listitem
><para
>Seleciona todo o texto no documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.clearSelection();
</synopsis
></term>
<listitem
><para
>Limpa a seleção de texto atual, sem remover o texto. </para
></listitem>
</varlistentry
></variablelist>
</para>
</sect3>
<sect3 id="dev-scripting-api-document">
<title
>API do Document</title>
<para
>Sempre que um script estiver em execução, existe um objeto global (variável) <quote
><literal
>document</literal
></quote
> representando o documento ativo atual. A seguir é apresentada uma lista de todas as funções disponíveis para o Document. <variablelist
><varlistentry>
<term
><synopsis
>String document.fileName();
</synopsis
></term>
<listitem
><para
>Devolve o nome do arquivo do documento, ou então um texto vazio para as janelas de texto ainda por salvar. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.url();
</synopsis
></term>
<listitem
><para
>Devolve o URL completo do documento, ou então um texto vazio para as janelas de texto ainda por salvar. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.mimeType();
</synopsis
></term>
<listitem
><para
>Devolve o tipo MIME do documento, ou então o tipo <literal
>application/octet-stream</literal
> se não for encontrado qualquer tipo MIME apropriado. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.encoding();
</synopsis
></term>
<listitem
><para
>Devolve a codificação usada atualmente para salvar o arquivo. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.highlightingMode();
</synopsis
></term>
<listitem
><para
>Devolve o modo de realce global usado para todo o documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.highlightingModeAt(<parameter
>Cursor <replaceable
>pos</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o modo de realce usado na posição do cursor indicada do documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Array document.embeddedHighlightingModes();
</synopsis
></term>
<listitem
><para
>Devolve uma lista com os modos de realce incorporados neste documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isModified();
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se o documento tiver alguma alteração por salvar, caso contrário devolve <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.text();
</synopsis
></term>
<listitem
><para
>Devolve o conteúdo inteiro do documento numa única sequência de texto. As mudanças de linha estão marcadas com o caractere de mudança de linha <quote
><literal
>\n</literal
></quote
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.text(<parameter
>int <replaceable
>daLinha</replaceable
></parameter
>, <parameter
>int <replaceable
>daColuna</replaceable
></parameter
>, <parameter
>int <replaceable
>paraLinha</replaceable
></parameter
>, <parameter
>int <replaceable
>paraColuna</replaceable
></parameter
>);
String document.text(<parameter
>Cursor <replaceable
>de</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>para</replaceable
></parameter
>);
String document.text(<parameter
>Range <replaceable
>intervalo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o texto no intervalo indicado. Recomenda-se que use a versão baseada nos cursores e nos intervalos, de modo a ter uma melhor visibilidade do código-fonte. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.line(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve a linha de texto indicada como uma sequência de texto. O texto devolvido fica em branco, caso a linha pedida esteja fora do intervalo. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.wordAt(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
String document.wordAt(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve a palavra na posição do cursor indicada. </para
></listitem>
</varlistentry>
<varlistentry>
<term>
<synopsis
>Range document.wordRangeAt(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
Range document.wordRangeAt(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis>
</term>
<listitem
><para
>Devolve o intervalo da palavra na posição indicada do cursor. O intervalo devolvido é inválido (ver Range.isValid()), caso a posição do texto esteja após o fim de uma linha. Se não existir nenhuma palavra no cursor indicado, é devolvido um intervalo vazio. </para>
<para
>Desde: &kde; 4.9 </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.charAt(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
String document.charAt(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o caractere 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 caractere na <replaceable
>linha</replaceable
> que não seja um espaço em branco. O primeiro caractere encontra-se na coluna 0. Se a linha estiver em branco ou conter apenas espaços, a string devolvida será vazia. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.lastChar(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o último caractere da <replaceable
>linha</replaceable
> indicada que não seja um espaço em branco. O primeiro caractere 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 caractere na posição indicada do cursor for um espaço em branco, caso contrário, devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.matchesAt(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>);
bool document.matchesAt(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se o <replaceable
>texto</replaceable
> indicado corresponder à posição indicada do cursor, caso contrário, devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.startsWith(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>, <parameter
>bool <replaceable
>ignorarEspacos</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se a linha começar por <replaceable
>texto</replaceable
>, caso contrário, devolve <literal
>false</literal
> (falso). O argumento <replaceable
>ignorarEspacos</replaceable
> controla se os espaços envolventes são ignorados ou não. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.endsWith(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>, <parameter
>bool <replaceable
>ignorarEspacos</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), caso a linha termine em <replaceable
>texto</replaceable
>, caso contrário devolve <literal
>false</literal
> (falso). O argumento <replaceable
>ignorarEspacos</replaceable
> controla se os espaços envolventes são ignorados. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.setText(<parameter
>String <replaceable
>texto</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Altera o texto do documento por inteiro. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.clear();
</synopsis
></term>
<listitem
><para
>Limpa o texto no documento por inteiro. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.truncate(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
bool document.truncate(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Trunca a linha indicada, na coluna ou posição do cursor indicadas. Devolve <literal
>true</literal
> (verdadeiro) em caso de sucesso ou <literal
>false</literal
> (falso) se a linha não estiver dentro do intervalo do documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.insertText(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>);
bool document.insertText(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Insere o <replaceable
>texto</replaceable
> na posição do cursor indicada. Devolve <literal
>true</literal
>, em caso de sucesso, ou <literal
>false</literal
> (falso), se o documento estiver apenas para leitura. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.removeText(<parameter
>int <replaceable
>daLinha</replaceable
></parameter
>, <parameter
>int <replaceable
>daColuna</replaceable
></parameter
>, <parameter
>int <replaceable
>paraLinha</replaceable
></parameter
>, <parameter
>int <replaceable
>paraColuna</replaceable
></parameter
>);
bool document.removeText(<parameter
>Cursor <replaceable
>de</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>para</replaceable
></parameter
>);
bool document.removeText(<parameter
>Range <replaceable
>intervalo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Remove o texto no intervalo indicado. Devolve <literal
>true</literal
> (verdadeiro), em caso de sucesso, ou <literal
>false</literal
> (falso), se o documento estiver no modo apenas para leitura. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.insertLine(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Insere o texto na linha indicada. Devolve <literal
>true</literal
> (verdadeiro), em caso de sucesso, ou <literal
>false</literal
> (falso), caso o documento esteja apenas para leitura ou se a linha não estiver no intervalo do documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.removeLine(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Remove a linha de texto indicada. Devolve <literal
>true</literal
> (verdadeiro), em caso de sucesso, ou <literal
>false</literal
> (falso), caso o documento esteja no modo apenas para leitura ou se a linha não estiver no intervalo do documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.wrapLine(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
bool document.wrapLine(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Reparte a linha na posição indicada pelo cursor. Devolve <literal
>true</literal
> (verdadeiro) em caso de sucesso ou <literal
>false</literal
> (falso) se, ⪚, a linha < 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
>bool document.isLineModified(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se a <replaceable
>linha</replaceable
> contém dados que não foram salvos. </para>
<para
>Desde: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isLineSaved(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se a <replaceable
>linha</replaceable
> foi alterada, mas o documento foi salvo. Assim, a linha não contém dados não salvos. </para>
<para
>Desde: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isLineTouched(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se a <replaceable
>linha</replaceable
> contém dados que não foram salvos ou foi anteriormente alterado. </para>
<para
>Desde: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.findTouchedLine(<parameter
>int <replaceable
>linhaInicial</replaceable
></parameter
>, <parameter
>bool <replaceable
>abaixo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Procura pela próxima linha tocada que comece na <replaceable
>linha</replaceable
>. A pesquisa é efetuada tanto para cima como para baixo, dependendo da direção de pesquisa indicada em <replaceable
>baixo</replaceable
>. </para>
<para
>Desde: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.length();
</synopsis
></term>
<listitem
><para
>Devolve o número de caracteres do documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.lineLength(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o comprimento da <replaceable
>linha</replaceable
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.editBegin();
</synopsis
></term>
<listitem
><para
>Inicia um grupo de edição para agrupar operações a desfazer/refazer. Certifique-se de invocar sempre o <function
>editEnd()</function
> tantas vezes quanto invoca o <function
>editBegin()</function
>. A invocação do <function
>editBegin()</function
> usa um contador de referências interno, &ie;, 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
> (&ie;, 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
>caractere</replaceable
></parameter
>, <parameter
>int <replaceable
>atributo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), caso o <replaceable
>caractere</replaceable
> e <replaceable
>atributo</replaceable
> indicados possam fazer parte de uma palavra, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.canBreakAt(<parameter
>String <replaceable
>caractere</replaceable
></parameter
>, <parameter
>int <replaceable
>atributo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se o <replaceable
>caractere</replaceable
> indicado com o <replaceable
>atributo</replaceable
> indicado for adequado para mudar de linha, caso contrário devolve <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.canComment(<parameter
>int <replaceable
>atributoInicial</replaceable
></parameter
>, <parameter
>int <replaceable
>atributoFinal</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (falso), caso um intervalo que começa e termina com os atributos indicados possa ser comentado; caso contrário, devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.commentMarker(<parameter
>int <replaceable
>atributo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o marcador de comentários, usado em linhas únicas, para um determinado <replaceable
>atributo</replaceable
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.commentStart(<parameter
>int <replaceable
>atributo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o marcador de início de comentários, usado em linhas múltiplas, para um determinado <replaceable
>atributo</replaceable
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.commentEnd(<parameter
>int <replaceable
>atributo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o marcador de fim de comentários, usado em linhas múltiplas, para um determinado <replaceable
>atributo</replaceable
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range document.documentRange();
</synopsis
></term>
<listitem
><para
>Devolve um intervalo que engloba todo o documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor documentEnd();
</synopsis
></term>
<listitem
><para
>Devolve um cursor posicionado na última coluna da última linha do documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool isValidTextPosition(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
bool isValidTextPosition(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se a posição atual do cursor estiver em uma posição de texto válida. Uma posição de texto é válida apenas se estiver localizada no início, no meio ou no fim de uma linha válida. Além disso, uma posição de texto é inválida se estiver localizada em um substituto Unicode. </para
><para
>Desde: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.attribute(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
int document.attribute(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o atributo na posição do cursor indicada. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isAttribute(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>, <parameter
>int <replaceable
>atributo</replaceable
></parameter
>);
bool document.isAttribute(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>int <replaceable
>atributo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se o atributo na posição do cursor indicada for igual a <replaceable
>atributo</replaceable
>, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.attributeName(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
String document.attributeName(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o nome do atributo como um texto legível. Isto é igual ao nome <literal
>itemData</literal
> dos arquivos de realce de sintaxe. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isAttributeName(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>, <parameter
>String <replaceable
>nome</replaceable
></parameter
>);
bool document.isAttributeName(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>String <replaceable
>nome</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro), se o nome do atributo, numa dada posição do cursor, corresponder ao <replaceable
>nome</replaceable
> indicado, caso contrário devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.variable(<parameter
>String <replaceable
>chave</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o valor da variável do documento identificada pela <replaceable
>chave</replaceable
>. Se a variável do documento não existir, o valor devolvido é um texto em branco. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.setVariable(<parameter
>String <replaceable
>chave</replaceable
></parameter
>, <parameter
>String <replaceable
>valor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Define o valor da variável do documento solicitada pela <replaceable
>chave</replaceable
>. </para>
<para
>Veja também: <link linkend="config-variables"
>Variáveis de documento do Kate</link
> </para>
<para
>Desde: &kde; 4.8 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.firstVirtualColumn(<parameter
>int <replaceable
>linha</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve a coluna virtual do primeiro caractere 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 caractere não-nulo na linha indicada, ou então <literal
>-1</literal
> se a linha estiver em branco ou só tiver caracteres de espaços em branco. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.toVirtualColumn(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
int document.toVirtualColumn(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
Cursor document.toVirtualCursor(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Converte a posição do cursor <quote
>real</quote
> para uma posição virtual, retornando um int ou um objeto Cursor. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.fromVirtualColumn(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>colunaVirtual</replaceable
></parameter
>);
int document.fromVirtualColumn(<parameter
>Cursor <replaceable
>cursorVirtual</replaceable
></parameter
>);
Cursor document.fromVirtualCursor(<parameter
>Cursor <replaceable
>cursorVirtual</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Converte a posição virtual do cursor para uma posição do cursor <quote
>real</quote
>, retornando um int ou um objeto Cursor. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor document.anchor(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>, <parameter
>Char <replaceable
>caractere</replaceable
></parameter
>);
Cursor document.anchor(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>Char <replaceable
>caractere</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Pesquisa para trás pelo caractere indicado, começando na posição do cursor indicada. Por exemplo, se for passado o '(', como caractere, esta função irá devolver a posição do '(' de abertura. Isto implica uma contagem das referências, &ie;, os outros '(...)' são ignorados. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor document.rfind(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>, <parameter
>int <replaceable
>atributo</replaceable
> = -1</parameter
>);
Cursor document.rfind(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>String <replaceable
>texto</replaceable
></parameter
>, <parameter
>int <replaceable
>atributo</replaceable
> = -1</parameter
>);
</synopsis
></term>
<listitem
><para
>Pesquisa para trás pelo texto indicado, com o <replaceable
>atributo</replaceable
> apropriado. O argumento <replaceable
>atributo</replaceable
> é ignorado se for igual a <literal
>-1</literal
>. O cursor devolvido é inválido, caso o texto não tenha sido encontrado. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.defStyleNum(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
int document.defStyleNum(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve o estilo padrão que é usado na posição do cursor indicada. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isCode(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
bool document.isCode(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se o atributo na posição do cursor indicada não for igual a todos os seguintes estilos: <literal
>dsComment</literal
>, <literal
>dsString</literal
>, <literal
>dsRegionMarker</literal
>, <literal
>dsChar</literal
>, <literal
>dsOthers</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isComment(<parameter
>int <replaceable
>linha</replaceable
></parameter
>, <parameter
>int <replaceable
>coluna</replaceable
></parameter
>);
bool document.isComment(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> se o atributo do caractere 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 caractere 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 caractere 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 caractere 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 caractere 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>
Generated by dwww version 1.15 on Fri Jun 28 06:06:52 CEST 2024.