<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
> <othercredit role="translator"
><firstname
>Marcus</firstname
><surname
>Gama</surname
><affiliation
><address
><email
>marcus.gama@gmail.com</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="https://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 C++, representada com realce de sintaxe.</phrase
></textobject>
<caption
><para
>Uma função C++, representada com realce de sintaxe.</para>
</caption>
</mediaobject>

<mediaobject>
<imageobject
><imagedata format="PNG" fileref="unhighlighted.png"/></imageobject>
<textobject
><phrase
>A mesma função C++, sem realce de sintaxe.</phrase
></textobject>
<caption
><para
>A mesma função C++, 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 &amp; 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>

</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 &HTML; 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
>O pacote &kappname; utiliza o framework de realce de sintaxe do pacote &kde-frameworks;. Os arquivos &XML; de realce padrão fornecidos com o pacote &kappname; são compilados na biblioteca de realce de sintaxe por padrão. </para>

<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
>, você encontra no <ulink url="https://commits.kde.org/syntax-highlighting?path=data/schema"
>Repositório de realce de sintaxe</ulink
> no arquivo <filename
>language.xsd</filename
> </para>

<para
>Os arquivos de definição de realce personalizados <filename class="extension"
>.xml</filename
> estão localizados em <filename class="directory"
>org.kde.syntax-highlighting/syntax/</filename
> na sua pasta de usuário, encontrada com <userinput
><command
>qtpaths</command
><option
> --paths GenericDataLocation</option
></userinput
> que geralmente são <filename class="directory"
><envar
>$HOME</envar
>/.local/share/</filename
> e <filename class="directory"
>/usr/share/</filename
>. </para>

<para
>Em pacotes Flatpak e Snap, o diretório acima não funcionará, pois o local dos dados é diferente para cada aplicativo. Em um aplicativo Flatpak, o local dos arquivos &XML; personalizados geralmente é <filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>nome-pacote-flatpak</replaceable
>/data/org.kde.syntax-highlighting/syntax/</filename
> e em um aplicativo Snap, esse local é <filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>nome-pacote-snap</replaceable
>/current/.local/share/org.kde.syntax-highlighting/syntax/</filename
>. </para>

<para
>No Windows, esses arquivos estão localizados em <filename
>%USERPROFILE%&#92;AppData&#92;Local&#92;org.kde.syntax-highlighting&#92;syntax</filename
>. <replaceable
>%USERPROFILE%</replaceable
> geralmente se expande para <filename
>C:&#92;Users&#92;<replaceable
>user</replaceable
></filename
>.</para>

<para
>Em resumo, para a maioria das configurações, o diretório de arquivos &XML; personalizados é o seguinte:</para>

<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry
>Para o usuário local</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.local/share/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>Para todos os usuários</entry>
<entry
><filename class="directory"
>/usr/share/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>Para pacotes Flatpak</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>nome-pacote-flatpak</replaceable
>/data/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>Para pacotes Snap</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>nome-pacote-snap</replaceable
>/current/.local/share/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>No &Windows;</entry>
<entry
><filename class="directory"
>%USERPROFILE%&#92;AppData&#92;Local&#92;org.kde.syntax-highlighting&#92;syntax</filename
></entry>
</row>
<row>
<entry
>No &macOS;</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/Library/Application Support/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para
>Se existirem vários arquivos para a mesma linguagem, o arquivo com o atributo de versão mais alto no elemento <userinput
>language</userinput
> será carregado.</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
>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
</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, &quot;*.cpp;*.h&quot;</para>
<para
>O <userinput
>version</userinput
> especifica a revisão atual do arquivo de definição em termos de um número inteiro. Sempre que você alterar um arquivo de definição de realce, certifique-se de aumentar esse número.</para>
<para
>O <userinput
>kateversion</userinput
> indica a última versão suportada pelo &kappname;.</para>

<para
>Atributos opcionais:</para>
<para
>O <userinput
>mimetype</userinput
> associa os arquivos do tipo &MIME;.</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 licença MIT para novos arquivos de realce de sintaxe.</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
>indenter</userinput
> define qual indentador será usado por padrão. Os indentadores disponíveis são: <emphasis
>ada, normal, cstyle, cmake, haskell, latex, lilypond, lisp, lua, pascal, python, replicode, ruby</emphasis
> e <emphasis
>xml</emphasis
>.</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
>&lt;language name=&quot;C++&quot; version=&quot;1&quot; kateversion=&quot;2.4&quot; section=&quot;Sources&quot; extensions=&quot;*.cpp;*.h&quot; /&gt;
</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
>Desde o &kde-frameworks; 5.53, uma lista pode incluir palavras-chave de outra lista ou linguagem/arquivo, usando o elemento <userinput
>include</userinput
>. O <userinput
>##</userinput
> é usado para separar o nome da lista e o nome da definição da linguagem, da mesma forma que na regra <userinput
>IncludeRules</userinput
>. Isso é útil para evitar a duplicação de listas de palavras-chave, caso você precise incluir as palavras-chave de outra linguagem/arquivo. Por exemplo, a lista <emphasis
>othername</emphasis
> contém a palavra-chave <emphasis
>str</emphasis
> e todas as palavras-chave da lista <emphasis
>types</emphasis
>, que pertence à linguagem <emphasis
>ISO C++</emphasis
>.</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
>&lt;highlighting&gt;
    &lt;list name=&quot;somename&quot;&gt;
      &lt;item&gt;class&lt;/item&gt;
      &lt;item&gt;const&lt;/item&gt;
    &lt;/list&gt;
    &lt;list name=&quot;othername&quot;&gt;
      &lt;item&gt;str&lt;/item&gt;
      &lt;include&gt;types##ISO C++&lt;/include&gt;
    &lt;/list&gt;
    &lt;contexts&gt;
      &lt;context attribute=&quot;Normal Text&quot; lineEndContext=&quot;#pop&quot; name=&quot;Normal Text&quot; &gt;
        &lt;keyword attribute=&quot;Keyword&quot; context=&quot;#stay&quot; String=&quot;somename&quot; /&gt;
        &lt;keyword attribute=&quot;Keyword&quot; context=&quot;#stay&quot; String=&quot;othername&quot; /&gt;
        &lt;DetectChar attribute=&quot;String&quot; context=&quot;string&quot; char=&quot;&amp;quot;&quot; /&gt;
      &lt;/context&gt;
      &lt;context attribute=&quot;String&quot; lineEndContext=&quot;#stay&quot; name=&quot;string&quot; &gt;
        &lt;DetectChar attribute=&quot;String&quot; context=&quot;#pop&quot; char=&quot;&amp;quot;&quot; /&gt;
      &lt;/context&gt;
    &lt;/contexts&gt;
    &lt;itemDatas&gt;
      &lt;itemData name=&quot;Normal Text&quot; defStyleNum=&quot;dsNormal&quot; /&gt;
      &lt;itemData name=&quot;Keyword&quot; defStyleNum=&quot;dsKeyword&quot; /&gt;
      &lt;itemData name=&quot;String&quot; defStyleNum=&quot;dsString&quot; /&gt;
    &lt;/itemDatas&gt;
  &lt;/highlighting&gt;
</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, recuo, linhas vazias e verificação ortográfica.</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>
<para
>As outras seções, <userinput
>folding</userinput
>, <userinput
>emptyLines</userinput
> e <userinput
>spellchecking</userinput
>, geralmente não são necessárias e serão explicadas posteriormente.</para>
<programlisting
>&lt;general&gt;
    &lt;comments&gt;
      &lt;comment name="singleLine" start="#"/&gt;
      &lt;comment name="multiLine" start="###" end="###" region="CommentFolding"/&gt;
    &lt;/comments&gt;
    &lt;keywords casesensitive="1"/&gt;
    &lt;folding indentationsensitive="0"/&gt;
    &lt;emptyLines&gt;
      &lt;emptyLine regexpr="\s+"/&gt;
      &lt;emptyLine regexpr="\s*#.*"/&gt;
    &lt;/emptyLines&gt;
    &lt;spellchecking&gt;
      &lt;encoding char="&#225;" string="\&#39;a"/&gt;
      &lt;encoding char="&#224;" string="\&#96;a"/&gt;
    &lt;/spellchecking&gt;
  &lt;/general&gt;
&lt;/language&gt;
</programlisting>
</listitem>
</varlistentry>

</variablelist>


</sect3>

<sect3 id="kate-highlight-sections">
<title
>As Seções em detalhes</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
>O <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
>attribute</userinput
> identifica o estilo a ser usado para um caractere quando nenhuma regra corresponde ou quando uma regra não especifica um atributo. Neste último caso, o <emphasis
>attribute</emphasis
> do contexto especificado no <emphasis
>context</emphasis
> da regra será usado.</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 (&eg;, 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
>. Também é possível alternar para um contexto que pertence a outra definição de linguagem, da mesma forma que nas regras <userinput
>IncludeRules</userinput
>, por exemplo, <userinput
>AlgumContexto##JavaScript</userinput
>. As mudanças de contexto também são descritas em <xref linkend="kate-highlight-rules-detailled"/>. Padrão: #stay.</para>
<para
>O <userinput
>lineEmptyContext</userinput
> define o contexto, se for encontrada uma linha em branco. A nomenclatura das mudanças de contexto é a mesma que a descrita anteriormente em <emphasis
>lineEndContext</emphasis
>. Padrão: #stay.</para>
<para
>O <userinput
>fallthroughContext</userinput
> especifica o próximo contexto para o qual alternar caso nenhuma regra corresponda. A nomenclatura das mudanças de contexto é a mesma descrita anteriormente em <emphasis
>lineEndContext</emphasis
>. Padrão: #stay.</para>
<para
>O <userinput
>fallthrough</userinput
> define se o sistema de realce alterna para o contexto especificado em <userinput
>fallthroughContext</userinput
> caso nenhuma regra corresponda. Observe que, desde o &kde; &frameworks; 5.62, este atributo está obsoleto em favor de <userinput
>fallthroughContext</userinput
>, pois, se o atributo <userinput
>fallthroughContext</userinput
> estiver presente, subentende-se implicitamente que o valor de <userinput
>fallthrough</userinput
> é <emphasis
>true</emphasis
>. Padrão: <emphasis
>false</emphasis
>.</para>
<para
>O <userinput
>noIndentationBasedFolding</userinput
> desativa o recolhimento baseado em indentação no contexto. Se o recolhimento baseado em indentação não estiver ativado, este atributo é inútil. Ele é definido no elemento <emphasis
>folding</emphasis
> do grupo <emphasis
>general</emphasis
>. 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
>.():!+,-&lt;=&gt;%&amp;*/;?[]^{|}~\</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 propriedades de comentário que são usadas para: <menuchoice
><guimenu
>Ferramentas</guimenu
><guimenuitem
>Comentar</guimenuitem
></menuchoice
>, <menuchoice
><guimenu
>Ferramentas</guimenu
><guimenuitem
>Descomentar</guimenuitem
></menuchoice
> e <menuchoice
><guimenu
>Ferramentas</guimenu
><guimenuitem
>Alternar comentário</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
>. Se escolher <emphasis
>singleLine</emphasis
>, poderá adicionar o atributo opcional <emphasis
>position</emphasis
>.</para>
<para
>O <userinput
>start</userinput
> define o texto usado para iniciar um comentário. No C++, este será o &quot;/*&quot; em comentários de várias linhas. Este atributo é obrigatório para os tipos <emphasis
>multiLine</emphasis
> e <emphasis
>singleLine</emphasis
>.</para>
<para
>O <userinput
>end</userinput
> define o texto usado para fechar um comentário. No C++, será o &quot;*/&quot;. Este atributo está disponível apenas e é obrigatório para comentários do tipo <emphasis
>multiLine</emphasis
>.</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. Este atributo está disponível apenas para o tipo <emphasis
>multiLine</emphasis
>.</para>
<para
>O <userinput
>position</userinput
> define onde o comentário de linha única é inserido. Por padrão, o comentário de linha única é colocado no início da linha na coluna 0, mas se você usar <emphasis
>position="afterwhitespace"</emphasis
> o comentário é inserido após os espaços em branco iniciais à direita, antes do primeiro caractere que não seja um espaço em branco. Isso é útil para colocar comentários corretamente em linguagens onde a indentação é importante, como Python ou YAML. Este atributo é opcional e o único valor possível é <emphasis
>afterwhitespace</emphasis
>. Isso só está disponível para o tipo <emphasis
>singleLine</emphasis
>.</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
>emptyLine</userinput
> no grupo <userinput
>emptyLines</userinput
> define quais linhas devem ser tratadas como linhas vazias. Isso permite modificar o comportamento do atributo <emphasis
>lineEmptyContext</emphasis
> nos elementos <userinput
>context</userinput
>. Os atributos disponíveis são:</term>

<listitem>
<para
>O <userinput
>regexpr</userinput
> define uma expressão regular que será tratada como uma linha em branco. Por padrão, linhas em branco não contêm nenhum caractere; portanto, isso adiciona linhas em branco adicionais, por exemplo, se você quiser que linhas com espaços também sejam consideradas linhas em branco. No entanto, na maioria das definições de sintaxe, você não precisa definir esse atributo.</para>
</listitem>
</varlistentry>


<varlistentry>
<term
>O elemento <userinput
>encoding</userinput
> no grupo <userinput
>spellchecking</userinput
> define uma codificação de caracteres para a verificação ortográfica. Atributos disponíveis:</term>

<listitem>
<para
>O <userinput
>char</userinput
> é um caractere codificado.</para>
<para
>O <userinput
>string</userinput
> é uma sequência de caracteres que será codificada como o caractere <emphasis
>char</emphasis
> na verificação ortográfica. Por exemplo, na linguagem LaTeX, a string <userinput
>\&quot;{A}</userinput
> representa o caractere <userinput
>&#196;</userinput
>.</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 (&eg; $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 + - * / :: &lt; &gt;</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
>&lt;NomeRegra attribute=&quot;(identificador)&quot; context=&quot;(identifier)&quot; [atributos específicos da regra] /&gt;</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
>). Um contexto vazio ou ausente é equivalente a <userinput
>#stay</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, &eg; <userinput
>#pop#pop!OtherContext</userinput
>.</para>
</listitem>
<listitem>
<para
>Um <emphasis
>identificador</emphasis
>, que é um nome de contexto, seguido por dois hashes (<userinput
>##</userinput
>) e outro <emphasis
>identificador</emphasis
>, que é o nome de uma definição de linguagem. Essa nomenclatura é similar à usada nas regras <userinput
>IncludeRules</userinput
> e permite que você alterne para um contexto pertencente a outra definição de realce de sintaxe, por exemplo, <userinput
>AlgumContexto##JavaScript</userinput
>. </para>
</listitem>
</itemizedlist>

<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. Todos os atributos são opcionais. </para>

<listitem>
<para
><emphasis
>attribute</emphasis
>: Um atributo mapeia-se para um <emphasis
>itemData</emphasis
> definido. Padrão: <emphasis
>attribute</emphasis
> do contexto especificado no atributo <emphasis
>context</emphasis
>.</para>
</listitem>
<listitem>
<para
><emphasis
>context</emphasis
>: Indica o contexto para onde muda o sistema de realce, se a regra corresponder. Padrão: #stay.</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, iniciando de 1. 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>

<para
><userinput
>Como isto funciona:</userinput
></para>

<para
>Nas <link linkend="regular-expressions"
>expressões regulares</link
> das regras <userinput
>RegExpr</userinput
>, todo o texto entre colchetes curvos simples <userinput
>(PADRÃO)</userinput
> é capturado e armazenado. Essas capturas podem ser usadas no contexto em que são alternadas, nas regras com o atributo <userinput
>dynamic</userinput
> <emphasis
>true</emphasis
>, por meio de <replaceable
>%N</replaceable
> (em <emphasis
>String</emphasis
>) ou <replaceable
>N</replaceable
> (em <emphasis
>char</emphasis
>).</para>

<para
>É importante mencionar que um texto capturado em uma regra <userinput
>RegEx</userinput
> é armazenado apenas para o contexto alterado, especificado em seu atributo <userinput
>context</userinput
>.</para>

<tip>
<itemizedlist>

<listitem>
<para
>Se as capturas não forem usadas, tanto por regras dinâmicas quanto na mesma expressão regular, grupos não capturantes devem ser usados: <userinput
>(?:PADRÃO)</userinput
></para>
<para
>Os grupos <emphasis
>lookahead</emphasis
> ou <emphasis
>lookbehind</emphasis
>, como <userinput
>(?=PADRÃO)</userinput
>, <userinput
>(?!PADRÃO)</userinput
> ou <userinput
>(?&lt;=PADRÃO)</userinput
>, não são capturados. Consulte <link linkend="regular-expressions"
>Expressões regulares</link
> para obter mais informações.</para>
</listitem>

<listitem>
<para
>Os grupos de captura podem ser usados ​​dentro da mesma expressão regular, usando <replaceable
>\N</replaceable
> em vez de <replaceable
>%N</replaceable
> respectivamente. Para mais informações, consulte <link linkend="regex-capturing"
>Capturando texto correspondente (referências anteriores)</link
> em <link linkend="regular-expressions"
>Expressões regulares</link
>.</para>
</listitem>

</itemizedlist>
</tip>

<para
>Exemplo 1:</para>
<para
>Neste exemplo simples, o texto correspondente à expressão regular <userinput
>=*</userinput
> é capturado e inserido em <replaceable
>%1</replaceable
> na regra dinâmica. Isso permite que o comentário termine com a mesma quantidade de <userinput
>=</userinput
> que no início. Isso corresponde a textos como: <userinput
>[[ comentário ]]</userinput
>, <userinput
>[=[ comentário ]=]</userinput
> ou <userinput
>[=====[ comentário ]=====]</userinput
>.</para>
<para
>Além disso, as capturas estão disponíveis apenas no contexto alternado para <emphasis
>Comentário de várias linhas</emphasis
>.</para>

<programlisting
>&lt;context name="Normal" attribute="Normal Text" lineEndContext="#stay"&gt;
  &lt;RegExpr context="Multi-line Comment" attribute="Comment" String="\[(=*)\[" beginRegion="RegionComment"/&gt;
&lt;/context&gt;
&lt;context name="Multi-line Comment" attribute="Comment" lineEndContext="#stay"&gt;
  &lt;StringDetect context="#pop" attribute="Comment" String="]%1]" dynamic="true" endRegion="RegionComment"/&gt;
&lt;/context&gt;
</programlisting>

<para
>Exemplo 2:</para>
<para
>Na regra dinâmica, <replaceable
>%1</replaceable
> corresponde à captura que corresponde a <userinput
>#+</userinput
>, e <replaceable
>%2</replaceable
> a <userinput
>&amp;quot;+</userinput
>. Isso corresponde ao texto como:<userinput
>#label""""dentro do contexto""""#</userinput
>.</para>
<para
>Essas capturas não estarão disponíveis em outros contextos, como <emphasis
>OtherContext</emphasis
>, <emphasis
>FindEscapes</emphasis
> ou <emphasis
>SomeContext</emphasis
>.</para>

<programlisting
>&lt;context name="SomeContext" attribute="Normal Text" lineEndContext="#stay"&gt;
  &lt;RegExpr context="#pop!NamedString" attribute="String" String="(#+)(?:[\w-]|[^[:ascii:]])(&amp;quot;+)"/&gt;
&lt;/context&gt;
&lt;context name="NamedString" attribute="String" lineEndContext="#stay"&gt;
  &lt;RegExpr context="#pop!OtherContext" attribute="String" String="%2(?:%1)?" dynamic="true"/&gt;
  &lt;DetectChar context="FindEscapes" attribute="Escape" char="\"/&gt;
&lt;/context&gt;
</programlisting>

<para
>Exemplo 3:</para>
<para
>Isso corresponde a textos como: <userinput
>Class::function&lt;T&gt;( ... )</userinput
>.</para>

<programlisting
>&lt;context name="Normal" attribute="Normal Text" lineEndContext="#stay"&gt;
  &lt;RegExpr context="FunctionName" lookAhead="true"
              String="\b([a-zA-Z_][\w-]*)(::)([a-zA-Z_][\w-]*)(?:&amp;lt;[\w\-\s]*&amp;gt;)?(\()"/&gt;
&lt;/context&gt;
&lt;context name="FunctionName" attribute="Normal Text" lineEndContext="#pop"&gt;
  &lt;StringDetect context="#stay" attribute="Class" String="%1" dynamic="true"/&gt;
  &lt;StringDetect context="#stay" attribute="Operator" String="%2" dynamic="true"/&gt;
  &lt;StringDetect context="#stay" attribute="Function" String="%3" dynamic="true"/&gt;
  &lt;DetectChar context="#pop" attribute="Normal Text" char="4" dynamic="true"/&gt;
&lt;/context&gt;
</programlisting>

<itemizedlist>
<title
>Delimitadores locais</title>
<para
>Algumas regras permitem os atributos opcionais <userinput
>weakDeliminator</userinput
> e <userinput
>additionalDeliminator</userinput
>, que são combinados com atributos de mesmo nome da tag <userinput
>keywords</userinput
>. Por exemplo, quando <userinput
>'%'</userinput
> é um delimitador fraco de <userinput
>keywords</userinput
>, ele pode se tornar um delimitador de palavras apenas para uma regra ao ser inserido em seu atributo <userinput
>additionalDeliminator</userinput
>. Sempre que uma regra permite esses atributos, ela conterá um <emphasis
>(delimitadores locais)</emphasis
>.</para>

<listitem>
<para
><emphasis
>weakDeliminator</emphasis
>: lista de caracteres que não atuam como delimitadores de palavras.</para>
</listitem>
<listitem>
<para
><emphasis
>additionalDeliminator</emphasis
>: define os delimitadores ou separadores adicionais.</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
>&lt;DetectChar char=&quot;(caractere)&quot; (atributos comuns) (dinâmico) /&gt;</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
>&lt;Detect2Chars char=&quot;(caractere)&quot; char1=&quot;(caractere)&quot; (atributos comuns) /&gt;</programlisting>
<para
>O atributo <userinput
>char</userinput
> define o primeiro caractere a ser procurado, e o atributo <userinput
>char1</userinput
> o segundo.</para>
<para
>Esta regra existe por razões históricas e, para facilitar a leitura, é preferível usar <userinput
>StringDetect</userinput
>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>AnyChar</term>
<listitem>
<para
>Detecta um caractere de um conjunto de caracteres especificados.</para>
<programlisting
>&lt;AnyChar String=&quot;(string)&quot; (atributos comuns) /&gt;</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
>&lt;StringDetect String=&quot;(string)&quot; [insensitive=&quot;true|false;&quot;] (atributos comuns) (dinâmico) /&gt;</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&lt;texto&gt;\b</userinput
> em termos de uma expressão regular, só que é mais rápido que a regra <userinput
>Exp Reg</userinput
>.</para>
<programlisting
>&lt;WordDetect String=&quot;(string)&quot; [insensitive=&quot;true|false;&quot;] (atributos comuns) (delimitadores locais) /&gt;</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
>&lt;RegExpr String=&quot;(texto)&quot; [insensitive=&quot;true|false&quot;] [minimal=&quot;true|false&quot;] (atributos comuns) (dinâmico) /&gt;</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
>&lt;keyword String=&quot;(nome da lista)&quot; (atributos comuns) (delimitadores locais) /&gt;</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
>. Também é possível usar o atributo <emphasis
>weakDeliminator</emphasis
> de <emphasis
>keyword</emphasis
> para que esta modificação se aplique apenas a esta regra.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>Int</term>
<listitem>
<para
>Detecta um número inteiro (como a expressão regular: <userinput
>\b[0-9]+</userinput
>).</para>
<para
><programlisting
>&lt;Int (atributos comuns) (delimitadores locais) /&gt;</programlisting
></para>
<para
>Esta regra não possui atributos específicos.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>Float</term>
<listitem>
<para
>Detecta um número de ponto flutuante (como a expressão regular: <userinput
>(\b[0-9]+\.[0-9]*|\.[0-9]+)([eE][-+]?[0-9]+)?</userinput
>).</para>
<para
><programlisting
>&lt;Float (atributos comuns) (delimitadores locais) /&gt;</programlisting
></para>
<para
>Esta regra não possui atributos específicos.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>HlCOct</term>
<listitem>
<para
>Detecta uma representação de número de ponto octal (como a expressão regular: <userinput
>\b0[0-7]+</userinput
>).</para>
<para
><programlisting
>&lt;HlCOct (atributos comuns) (delimitadores locais) /&gt;</programlisting
></para>
<para
>Esta regra não possui atributos específicos.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>HlCHex</term>
<listitem>
<para
>Detecta uma representação numérica hexadecimal (como uma expressão regular: <userinput
>\b0[xX][0-9a-fA-F]+</userinput
>).</para>
<para
><programlisting
>&lt;HlCHex (atributos comuns) (delimitadores locais) /&gt;</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
>&lt;HlCStringChar (atributos comuns) /&gt;</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&quot;'?\</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
>&lt;HlCChar (atributos comuns) /&gt;</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
>&lt;RangeDetect char=&quot;(caractere)&quot;  char1=&quot;(caractere)&quot; (atributos comuns) /&gt;</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
>&lt;LineContinue (atributos comuns) [char="\"] /&gt;</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
>&lt;IncludeRules context=&quot;ligacao_contexto&quot; [includeAttrib=&quot;true|false&quot;] /&gt;</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
>&lt;IncludeRules context=&quot;outroContexto&quot; /&gt;</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
>&lt;IncludeRules context=&quot;String##C++&quot; /&gt;</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
>&lt;DetectSpaces (atributos comuns) /&gt;</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 a expressão regular: <userinput
>[a-zA-Z_][a-zA-Z0-9_]*</userinput
>).</para>
<programlisting
>&lt;DetectIdentifier (atributos comuns) /&gt;</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 &amp; 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
>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
>&lt;RegExpr attribute=&quot;Macro&quot; context=&quot;macro&quot; String=&quot;^\s*#&quot; /&gt;</programlisting
> Você poderá obter o mesmo se usar: <programlisting
>&lt;DetectChar attribute=&quot;Macro&quot; context=&quot;macro&quot; char=&quot;#&quot; firstNonSpace=&quot;true&quot; /&gt;</programlisting
> Se quiser corresponder à expressão regular <userinput
>'^#'</userinput
>, poderá usar ainda o <userinput
>DetectChar</userinput
> com o atributo <userinput
>column=&quot;0&quot;</userinput
>. O atributo <userinput
>column</userinput
> conta como caracteres; assim, uma tabulação conta como se fosse apenas um caractere. </para>
</listitem>
<listitem>
<para
>Nas regras <userinput
>RegExpr</userinput
>, use o atributo <userinput
>column="0"</userinput
> se o padrão <userinput
>^PADRÃO</userinput
> for usado para encontrar correspondências no início de uma linha. Isso melhora o desempenho, pois evita a busca por correspondências nas demais colunas.</para>
</listitem>
<listitem>
<para
>Em expressões regulares, use grupos não capturantes <userinput
>(?:PADRÃO)</userinput
> em vez de grupos capturantes <userinput
>(PADRÃO)</userinput
>, se as capturas não forem usadas na mesma expressão regular ou em regras dinâmicas. Isso evita o armazenamento desnecessário de capturas.</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
>&lt;StringDetect attribute=&quot;Comment&quot; context=&quot;#pop&quot; String=&quot;*/&quot; lookAhead=&quot;true&quot; /&gt;</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ê pode validar todos os arquivos &XML; usando o comando <command
>validatehl.sh mySyntax.xml</command
>. O arquivo <filename
>validatehl.sh</filename
> usa <filename
>language.xsd</filename
> que estão disponíveis no <ulink url="https://commits.kde.org/syntax-highlighting?path=data/schema"
>Repositório de realce de sintaxe</ulink
>. </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
>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE language
[
        &lt;!ENTITY myref    "[A-Za-z_:][\w.:_-]*"&gt;
]&gt;
</programlisting>
<para
>Agora, você poderá usar o <emphasis
>&amp;referencia;</emphasis
> em vez da expressão regular.</para>
</listitem>
<listitem>
<para
>No editor do Kate, você pode recarregar as sintaxes usando a linha de comando integrada (atalho <userinput
>F7</userinput
> por padrão) e o comando <command
>reload-highlighting</command
>.</para>
</listitem>
<listitem>
<para
>Você pode usar o utilitário de linha de comando chamado <userinput
>ksyntaxhighlighter6</userinput
> (<userinput
>kate-syntax-highlighter</userinput
> em versões mais antigas) para testar uma sintaxe e exibir o estilo e as regiões associadas a cada parte de um texto.</para>

<mediaobject>
<imageobject
><imagedata format="PNG" fileref="ksyntaxhighlighter6-trace-format.png"/></imageobject>
<textobject
><phrase
>Resultado de <command
>ksyntaxhighlighter6 --output-format=ansi --syntax-trace=format test.cpp</command
>.</phrase
></textobject>
<caption
><para
>Resultado de <command
>ksyntaxhighlighter6 --output-format=ansi --syntax-trace=format test.cpp</command
>.</para>
</caption>
</mediaobject>

<para
>Use <command
>ksyntaxhighlighter6 -h</command
> para mais opções.</para>
</listitem>
</itemizedlist>
</sect3>

</sect2>

</sect1>


<sect1 id="color-themes">
<title
>Trabalhando com temas de cores</title>

<sect2 id="color-themes-overview">

<title
>Introdução</title>

<para
>Os temas de cores definem as cores da <link linkend="kate-part"
>área de edição de texto</link
> e do <link linkend="highlight"
>realce de sintaxe</link
>. Um tema de cores engloba o seguinte: <itemizedlist>
<listitem
><para
>O estilo do texto, usado para realce de sintaxe através dos <emphasis
>atributos de estilo padrão</emphasis
>. Por exemplo, a cor do texto e a cor do texto selecionada.</para
></listitem>
<listitem
><para
>O plano de fundo da área de edição de texto, incluindo a seleção de texto e a linha atual.</para
></listitem>
<listitem
><para
>A borda do ícone da área de texto: seu fundo, a linha separadora, os números de linha, os marcadores de quebra de linha, as marcas de linha modificadas e o recolhimento de código.</para
></listitem>
<listitem
><para
>Decoradores de texto, como marcadores de pesquisa, recuo e marcas de tabulação/espaço, a correspondência de parênteses e a verificação ortográfica.</para
></listitem>
<listitem
><para
>Favoritos e trechos de código.</para
></listitem>
</itemizedlist>
</para>

<para
>Para evitar confusão, o seguinte está fora do escopo: <itemizedlist>
<listitem
><para
>O tipo e o tamanho da fonte.</para
></listitem>
<listitem
><para
>As cores do aplicativo de edição de texto, como o mapa da barra de rolagem, os menus, a barra de abas, a cor da janela, etc. Em aplicativos do &kde;, como o &kate; ou o &kdevelop;, essas cores são definidas pelo <userinput
>esquema de cores global do &kde; &plasma;</userinput
>, que é configurado no módulo <ulink url="help:/kcontrol/colors/"
><quote
>Cores</quote
> em &systemsettings;</ulink
> ou no próprio aplicativo, no menu <menuchoice
><guimenu
>Configurações</guimenu
><guisubmenu
>Esquema de cores</guisubmenu
></menuchoice
>. </para
></listitem>
</itemizedlist>
</para>

<mediaobject>
<imageobject
><imagedata format="PNG" fileref="breeze-color-theme-preview.png"/></imageobject>
<textobject
><phrase
>Temas de cores <quote
>Breeze Light</quote
> e <quote
>Breeze Dark</quote
> com realce de sintaxe para <quote
>C++</quote
>.</phrase>
</textobject>
<caption
><para
>Temas de cores <quote
>Breeze Light</quote
> e <quote
>Breeze Dark</quote
> com realce de sintaxe para <quote
>C++</quote
>.</para>
</caption>
</mediaobject>

</sect2>

<sect2 id="color-themes-ksyntaxhighlighting">

<title
>O temas de cores do KSyntaxHighlighting</title>

<para
>O framework <ulink url="https://api.kde.org/frameworks/syntax-highlighting/html/"
>KSyntaxHighlighting</ulink
>, que é o <link linkend="highlight"
>mecanismo de realce de sintaxe</link
>, é a biblioteca que <userinput
>fornece e gerencia os temas de cores</userinput
>. Isso faz parte do &kde; &frameworks; e é usado no editores de texto do &kde; como o <ulink url="https://apps.kde.org/en/kate"
>&kate;</ulink
>, <ulink url="https://apps.kde.org/en/kwrite"
>&kwrite;</ulink
>, <ulink url="https://apps.kde.org/en/kile"
>&kile;</ulink
> e <ulink url="https://apps.kde.org/en/kdevelop"
>&kdevelop;</ulink
>. Essa dependência se parece com o seguinte:</para>

<mediaobject>
<imageobject
><imagedata format="PNG" fileref="kf5-ksyntaxhighlighting.png"/></imageobject>
<textobject
><phrase
>Dependência das bibliotecas do &kde; &frameworks; 5 em editores de texto.</phrase
></textobject>
<caption
><para
>Dependência das bibliotecas do &kde; &frameworks; em editores de texto.</para>
</caption>
</mediaobject>

<para
>O KSyntaxHighlighting inclui uma variedade de temas integrados que são exibidos na página <ulink url="https://kate-editor.org/themes/"
><quote
>Temas de cores</quote
> do site do editor Kate</ulink
>.</para>

<para
>O framework <ulink url="https://api.kde.org/frameworks/ktexteditor/html/"
>KTextEditor</ulink
>, que é o mecanismo de edição de texto, fornece uma interface de usuário para criar e editar temas de cores, incluindo uma ferramenta para importar e exportar temas. Esta é a maneira mais simples de criar e editar temas; você pode acessá-la através da janela <link linkend="config-dialog"
><quote
>Configurar</quote
></link
> do editor de texto. Mais detalhes em <xref linkend="color-themes-gui"/>.</para>

<mediaobject>
<imageobject
><imagedata format="PNG" fileref="color-themes-gui-breeze-dark-default-text-styles.png"/></imageobject>
<textobject
><phrase
>A &GUI; para gerenciar temas de cores nas configurações do &kate;.</phrase
></textobject>
<caption
><para
>A &GUI; para gerenciar temas de cores nas configurações do &kate;.</para>
</caption>
</mediaobject>

<para
>É importante mencionar que, nos editores de texto do &kde;, como o &kate; ou o &kdevelop;, os temas de cores do KSyntaxHighlighting são usados ​​ <ulink url="https://kate-editor.org/post/2020/2020-09-13-kate-color-themes-5.75/"
>desde o &kde; &frameworks; 5.75</ulink
>, lançado em 10 de outubro de 2020. Anteriormente, os esquemas de cores do &kate; (configuração de esquema baseada em KConfig) eram usados ​​e agora estão obsoletos. No entanto, é possível converter os antigos esquemas do &kate; para os temas de cores do KSyntaxHighlighting. O <ulink url="https://invent.kde.org/frameworks/syntax-highlighting"
>repositório do KSyntaxHighlighting</ulink
> inclui o script <userinput
>utils/kateschema_to_theme_converter.py</userinput
> e o utilitário <userinput
>utils/schema-converter/</userinput
> para essa finalidade. </para>

</sect2>

<sect2 id="color-themes-json">

<title
>Formato &JSON; dos temas de cores</title>

<sect3 id="color-themes-json-overview">

<title
>Introdução</title>

<para
>Os temas de cores são armazenados em arquivos no formato &JSON;, com a extensão <userinput
>.theme</userinput
>.</para>

<para
>No código-fonte do <ulink url="https://invent.kde.org/frameworks/syntax-highlighting"
>KSyntaxHighlighting</ulink
>, os arquivos &JSON; dos temas integrados estão localizados no diretório <userinput
>data/themes/</userinput
>. Observe que nos editores de texto, os temas integrados são compilados na biblioteca KSyntaxHighlighting; portanto, a maneira de acessá-los é por meio do código-fonte ou <link linkend="color-themes-gui-import-export"
>exportando-os da &GUI; para gerenciar temas do KTextEditor</link
>.</para>

<para
>Também é possível adicionar facilmente temas adicionais ou personalizados, que são carregados do sistema de arquivos. Os arquivos de tema personalizados pelo usuário estão localizados na pasta <filename class="directory"
>org.kde.syntax-highlighting/themes/</filename
> na sua pasta de usuário, que você pode encontrar com o comando <userinput
><command
>qtpaths</command
><option
> --paths GenericDataLocation</option
></userinput
> e geralmente são <filename class="directory"
><envar
>$HOME</envar
>/.local/share/</filename
> e <filename class="directory"
>/usr/share/</filename
>. </para>

<para
>Em pacotes Flatpak e Snap, a pasta acima não funcionará, pois o local dos dados é diferente para cada aplicativo. Em um aplicativo Flatpak, o local dos arquivos de tema personalizados geralmente é <filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>nome-pacote-flatpak</replaceable
>/data/org.kde.syntax-highlighting/themes/</filename
> e em um aplicativo Snap, esse local é <filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>nome-pacote-snap</replaceable
>/current/.local/share/org.kde.syntax-highlighting/themes/</filename
>. </para>

<para
>No &Windows;, esses arquivos estão localizados em <filename
>%USERPROFILE%&#92;AppData&#92;Local&#92;org.kde.syntax-highlighting&#92;themes</filename
>. <replaceable
>%USERPROFILE%</replaceable
> geralmente se expande para <filename
>C:&#92;Users&#92;<replaceable
>nome-de-usuário</replaceable
></filename
>.</para>

<para
>Em resumo, para a maioria das configurações, a pasta de temas personalizados é a seguinte:</para>

<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry
>Para o usuário local</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.local/share/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>Para todos os usuários</entry>
<entry
><filename class="directory"
>/usr/share/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>Para pacotes Flatpak</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>nome-pacote-flatpak</replaceable
>/data/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>Para pacotes Snap</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>nome-pacote-snap</replaceable
>/current/.local/share/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>No &Windows;</entry>
<entry
><filename class="directory"
>%USERPROFILE%&#92;AppData&#92;Local&#92;org.kde.syntax-highlighting&#92;themes</filename
></entry>
</row>
<row>
<entry
>No &macOS;</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/Library/Application Support/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para
>Se existirem vários arquivos de tema com o mesmo nome, o arquivo com a <userinput
>revision</userinput
> mais alta será carregado. </para>

</sect3>

<sect3 id="color-themes-json-basic">

<title
>A estrutura &JSON;</title>

<para
>A estrutura de um arquivo &JSON; é explicada em <ulink url="https://www.json.org"
>seu site</ulink
>. Basicamente, um arquivo no formato JSON consiste em: <itemizedlist>
<listitem
><para
>Coleções de pares chave/valor, separados por vírgulas e agrupados em <userinput
>{ }</userinput
> que chamaremos de <quote
>objetos</quote
>.</para
></listitem>
<listitem
><para
>Listas ordenadas de valores, separados por vírgulas e agrupados em <userinput
>[ ]</userinput
> que chamaremos de <quote
>array</quote
>.</para
></listitem
></itemizedlist>
</para>

<para
>A nomenclatura <quote
>chave</quote
>, <quote
>valor</quote
>, <quote
>objeto</quote
> e <quote
>array</quote
> será usada neste artigo. Se esta for a sua primeira vez trabalhando com arquivos &JSON;, entendê-los é tão simples quanto observar os exemplos abaixo. </para>

</sect3>

<sect3 id="color-themes-json-root">

<title
>Seções principais dos arquivos de tema de cores &JSON;</title>

<para
>O objeto raiz do arquivo &JSON; do tema de cores contém o seguinte esquema de chaves:</para>

<itemizedlist>
<listitem
><para
><userinput
>metadata</userinput
>: É obrigatória. O valor é um objeto com os metadados do tema, como nome, revisão e licença.</para>
<para
>Isto é detalhado em <xref linkend="color-themes-json-metadata"/>.</para>
</listitem>

<listitem
><para
><userinput
>editor-colors</userinput
>: É obrigatória. O valor é um objeto com as cores da área de edição de texto, como o fundo, a borda do ícone e a decoração do texto.</para>
<para
>Isto é detalhado em <xref linkend="color-themes-editor-colors"/>.</para>
</listitem>

<listitem
><para
><userinput
>text-styles</userinput
>: É obrigatória. O valor é um objeto com os atributos de <emphasis
>estilo de texto padrão</emphasis
> da sintaxe realce de sintaxe. Cada atributo define sua <emphasis
>cor do texto</emphasis
>, sua <emphasis
>cor do texto selecionada</emphasis
> ou se está em <emphasis
>negrito</emphasis
> ou <emphasis
>itálico</emphasis
>, por exemplo. Os estilos de texto podem ser referenciados a partir dos <link linkend="kate-highlight-default-styles"
>arquivos XML de definição de sintaxe</link
>.</para>
<para
>Isto é detalhado em <xref linkend="color-themes-text-styles"/>.</para>
</listitem>

<listitem
><para
><userinput
>custom-styles</userinput
>: É opcional. Define estilos de texto para os atributos de definições específicas de realce de sintaxe. Por exemplo, em uma definição de realce como <userinput
>Python</userinput
> ou <userinput
>Markdown</userinput
> você pode especificar um estilo de texto diferente que substitui o padrão definido em <userinput
>text-styles</userinput
>.</para>
<para
>Isto é detalhado em <xref linkend="color-themes-custom-styles"/>.</para>
</listitem>
</itemizedlist>

<para
>A linguagem &JSON; não suporta comentários. No entanto, você pode usar a chave opcional <userinput
>_comments</userinput
> no objeto raiz para escrever comentários. Por exemplo, se você estiver adaptando um tema existente, pode inserir a URL do repositório original. A maneira mais prática é usar um array de strings. </para>

<para
>Abaixo está um arquivo de exemplo para o tema <quote
>Breeze Light</quote
>. Você pode notar que, para evitar que o exemplo fique muito grande, os objetos <userinput
>editor-colors</userinput
> e <userinput
>text-styles</userinput
> não contêm todas as chaves necessárias. Você pode ver o arquivo completo do <ulink url="https://invent.kde.org/frameworks/syntax-highlighting/-/blob/master/data/themes/breeze-light.theme"
>tema <quote
>Breeze Light</quote
> no repositório do KSyntaxHighlighting</ulink
>. </para>

<programlisting
>{
    "_comments": [
        "Isto é um comentário.",
        "Se o tema for uma adaptação de outro, coloque o link para o repositório original."
    ],
    "metadata": {
        "name" : "Breeze Light",
        "revision" : 5,
        "copyright": [
            "SPDX-FileCopyrightText: 2016 Volker Krause &lt;vkrause@kde.org&gt;",
            "SPDX-FileCopyrightText: 2016 Dominik Haumann &lt;dhaumann@kde.org&gt;"
        ],
        "license": "SPDX-License-Identifier: MIT"
    },
    "editor-colors": {
        "BackgroundColor" : "#ffffff",
        "CodeFolding" : "#94caef",
        "BracketMatching" : "#ffff00",
        "CurrentLine" : "#f8f7f6",
        "IconBorder" : "#f0f0f0",
        "IndentationLine" : "#d2d2d2",
        "LineNumbers" : "#a0a0a0",
        "CurrentLineNumber" : "#1e1e1e",
        <replaceable
>As outras chaves de cor do editor...</replaceable>

    },
    "text-styles": {
        "Normal" : {
            "text-color" : "#1f1c1b",
            "selected-text-color" : "#ffffff",
            "bold" : false,
            "italic" : false,
            "underline" : false,
            "strike-through" : false
        },
        "Keyword" : {
            "text-color" : "#1f1c1b",
            "selected-text-color" : "#ffffff",
            "bold" : true
        },
        "Function" : {
            "text-color" : "#644a9b",
            "selected-text-color" : "#452886"
        },
        "Variable" : {
            "text-color" : "#0057ae",
            "selected-text-color" : "#00316e"
        },
        <replaceable
>As outras chaves de estilo de texto...</replaceable>

    },
    "custom-styles": {
        "ISO C++": {
            "Data Type": {
                "bold": true,
                "selected-text-color": "#009183",
                "text-color": "#00b5cf"
            },
            "Keyword": {
                "text-color": "#6431b3"
            }
        },
        "YAML": {
            "Attribute": {
                "selected-text-color": "#00b5cf",
                "text-color": "#00b5cf"
            }
        }
    }
}
</programlisting>

</sect3>

<sect3 id="color-themes-json-metadata">

<title
>Metadados</title>

<para
>O objeto &JSON; da chave <userinput
>metadata</userinput
> contém informações relevantes sobre o tema. Este objeto possui as seguintes chaves: <itemizedlist>
<listitem
><para
><userinput
>nome</userinput
>: É uma <emphasis
>string</emphasis
> que define o nome da linguagem. Ela aparece nos menus e diálogos posteriormente. É obrigatória.</para
></listitem>

<listitem
><para
><userinput
>revision</userinput
>: É um <emphasis
>número inteiro</emphasis
> que especifica a revisão atual do arquivo de tema. Sempre que você atualizar um arquivo de tema de cores, certifique-se de incrementar esse número. É obrigatória.</para
></listitem>

<listitem
><para
><userinput
>license</userinput
>: É uma <emphasis
>string</emphasis
> que define a licença do tema, usando o identificador <userinput
>SPDX-License-Identifier</userinput
> do formato de comunicação de licença padrão <ulink url="https://spdx.dev/"
>SPDX</ulink
>. É opcional.</para>
<para
>Você pode ver a lista completa de identificadores de licença SPDX <ulink url="https://spdx.org/licenses/"
>aqui</ulink
>.</para
></listitem>

<listitem
><para
><userinput
>copyright</userinput
>: É uma <emphasis
>array</emphasis
> de <emphasis
>strings</emphasis
> que especifica os autores do tema, usando o identificador <userinput
>SPDX-FileCopyrightText</userinput
> do formato de comunicação de licença padrão <ulink url="https://spdx.dev/"
>SPDX</ulink
>. É opcional.</para
></listitem>
</itemizedlist>
</para>

<programlisting
>"metadata": {
    "name" : "Breeze Light",
    "revision" : 5,
    "copyright": [
        "SPDX-FileCopyrightText: 2016 Volker Krause &lt;vkrause@kde.org&gt;",
        "SPDX-FileCopyrightText: 2016 Dominik Haumann &lt;dhaumann@kde.org&gt;"
    ],
    "license": "SPDX-License-Identifier: MIT"
}
</programlisting>

</sect3>

</sect2>

<sect2 id="color-themes-editing">

<title
>Cores em detalhes</title>

<para
>Esta seção detalha todos os atributos de cor disponíveis e as configurações de cor disponíveis.</para>

<sect3 id="color-themes-editor-colors">

<title
>Cores do editor</title>

<para
>Corresponde às cores da <link linkend="kate-part"
>área de edição de texto</link
>.</para>

<para
>No <link linkend="color-themes-json"
>arquivo de tema &JSON;</link
>, a chave respectiva <userinput
>editor-colors</userinput
> tem como valor um <emphasis
>objeto</emphasis
> onde cada chave referencia um atributo de cor do editor de texto. Aqui, <userinput
>todas as chaves disponíveis são obrigatórias</userinput
>, seus valores são <userinput
>strings</userinput
> com códigos de cores hexadecimais, como <quote
>#00B5CF</quote
>. </para>

<para
>Na <link linkend="color-themes-gui"
>&GUI; para gerenciar temas do KTextEditor</link
>, esses atributos podem ser modificados na aba <userinput
><guilabel
>Cores</guilabel
></userinput
>. </para>

<para
>As chaves disponíveis são as seguintes; as chaves usadas no arquivo <link linkend="color-themes-json"
>&JSON;</link
> estão listadas em <emphasis
>negrito</emphasis
>, os nomes usados na <link linkend="color-themes-gui"
>&GUI;</link
> são mostrados entre parênteses. </para>

<variablelist>

<varlistentry id="variable-prefcolors-colors-text-background">
<term
><guilabel
>Cores de fundo do editor</guilabel
></term>
<listitem>

<variablelist>

<varlistentry id="variable-pref-colors-normal-text">
<term
><userinput
>BackgroundColor</userinput
> (<guilabel
>Área do texto</guilabel
>)</term>
<listitem
><para
>Este é o plano de fundo padrão para a área do editor; será a cor dominante.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-BackgroundColor.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>

<varlistentry id="variable-pref-colors-selected-text">
<term
><userinput
>TextSelection</userinput
> (<guilabel
>Texto selecionado</guilabel
>)</term>
<listitem
><para
>Este é o fundo para o texto selecionado. </para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-TextSelection.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>

<varlistentry id="variable-pref-colors-current-line">
<term
><userinput
>CurrentLine</userinput
> (<guilabel
>Linha atual</guilabel
>)</term>
<listitem
><para
>Define a cor da linha atual. Se configurar esta cor um pouco diferente do fundo do texto normal, isto o ajudará a concentrar-se na linha atual. </para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-CurrentLine.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>

<varlistentry id="variable-pref-colors-search-highlight">
<term
><userinput
>SearchHighlight</userinput
> (<guilabel
>Pesquisar realce</guilabel
>)</term>
<listitem
><para
>Define a cor do texto que corresponda à sua última pesquisa. </para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-SearchHighlight.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>

<varlistentry id="variable-pref-colors-replace-highlight">
<term
><userinput
>ReplaceHighlight</userinput
> (<guilabel
>Substituir realce</guilabel
>)</term>
<listitem
><para
>Define a cor do texto que corresponda à sua última operação de substituição.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-ReplaceHighlight.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>

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

<varlistentry id="variable-prefcolors-colors-icon-border">
<term
><guilabel
>Borda do ícone</guilabel
></term>
<listitem>
<variablelist>

<varlistentry>
<term
><userinput
>IconBorder</userinput
> (<guilabel
>Área de fundo</guilabel
>)</term>
<listitem
><para
>Esta cor é usada para as marcas, números de linhas e bordas das marcações de desdobramento do lado esquerdo da janela de edição, quando forem apresentados. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>LineNumbers</userinput
> (<guilabel
>Números de linha</guilabel
>)</term>
<listitem
><para
>Esta cor é usada para desenhar os números de linha do lado esquerdo da janela, quando estiverem visíveis.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>CurrentLineNumber</userinput
> (<guilabel
>Número da linha atual</guilabel
>)</term>
<listitem
><para
>Esta cor é usada para desenhar o número da linha atual, no lado esquerdo da visualização. Definir isso um pouco diferente de <quote
>LineNumbers</quote
> ajuda a manter o foco na linha atual. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>Separator</userinput
> (<guilabel
>Separador</guilabel
>)</term>
<listitem
><para
>Esta cor é usada para desenhar a linha vertical que separa a borda do ícone do fundo da área de texto.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-IconBorder.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>WordWrapMarker</userinput
> (<guilabel
>Marcador de quebra de linha</guilabel
>)</term>
<listitem
><para
>Esta cor é usada para desenhar um padrão à esquerda das linhas repartidas com quebra de linha, quando estiverem alinhadas na vertical, assim como para as marcações de quebras de linha estáticas.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-WordWrapMarker.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>CodeFolding</userinput
> (<guilabel
>Dobradura de código</guilabel
>)</term>
<listitem
><para
>Esta cor é usada para destacar a seção de código que será recolhida quando você clicar na seta de recolhimento de código à esquerda de um documento. Para mais informações, consulte a <link linkend="advanced-editing-tools-code-folding"
>documentação de recolhimento de código</link
>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-CodeFolding.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>ModifiedLines</userinput
> (<guilabel
>Linhas modificadas</guilabel
>)</term>
<listitem
><para
>Esta cor é usada para destacar à esquerda de um documento as linhas que foram modificadas, mas ainda não salvas. Para mais informações, consulte <xref linkend="kate-part-line-modification"/>.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>SavedLines</userinput
> (<guilabel
>Linhas salvas</guilabel
>)</term>
<listitem
><para
>Esta cor é usada para destacar à esquerda de um documento as linhas que foram modificadas nesta sessão e salvas. Para mais informações, consulte <xref linkend="kate-part-line-modification"/>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-ModifiedLines.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>

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

<varlistentry id="variable-prefcolors-colors-text-decorations">
<term
><guilabel
>Decorações de texto</guilabel
></term>
<listitem>
<variablelist>

<varlistentry>
<term
><userinput
>SpellChecking</userinput
> (<guilabel
>Linha com erro de ortografia</guilabel
>)</term>
<listitem
><para
>Esta cor é usada para indicar erros ortográficos.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-SpellChecking.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>TabMarker</userinput
> (<guilabel
>Marcadores de espaço e tabulação</guilabel
>)</term>
<listitem
><para
>Esta cor é usada para desenhar os indicadores de espaços em branco, quando eles estiverem ativos.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-TabMarker.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>IndentationLine</userinput
> (<guilabel
>Recuo da linha</guilabel
>)</term>
<listitem
><para
>Esta cor é usada para desenhar uma linha à esquerda de blocos recuados, se <link linkend="appearance-general"
>esse recurso estiver ativado</link
>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-IndentationLine.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>BracketMatching</userinput
> (<guilabel
>Realce de parênteses</guilabel
>)</term>
<listitem
><para
>Esta cor é usada para desenhar o fundo dos parênteses correspondentes. </para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-BracketMatching.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>

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

<varlistentry id="variable-prefcolors-colors-marker-colors">
<term
><guilabel
>Cores dos marcadores</guilabel
></term>
<listitem>
<variablelist>

<varlistentry>
<term
><userinput
>MarkBookmark</userinput
> (<guilabel
>Favorito</guilabel
>)</term>
<listitem
><para
>Esta cor é usada para indicar marcadores. Observe que esta cor tem uma opacidade de 22% (e 33% para a linha atual) em relação ao fundo. Para mais informações, consulte <xref linkend="kate-part-bookmarks"/>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-MarkBookmark.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>MarkBreakpointActive</userinput
> (<guilabel
>Ponto de parada ativo</guilabel
>)</term>
<listitem
><para
>Esta cor é usada pelo plugin GDB para indicar um ponto de parada ativo. Observe que esta cor tem opacidade em relação ao fundo. Para mais informações, consulte <ulink url="help:/kate/kate-application-plugin-gdb.html"
>a documentação do plugin GDB</ulink
>.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>MarkBreakpointReached</userinput
> (<guilabel
>Ponto de parada atingido</guilabel
>)</term>
<listitem
><para
>Esta cor é usada pelo plugin GDB para indicar um ponto de parada que você atingiu durante a depuração. Observe que esta cor tem opacidade em relação ao fundo. Para obter mais informações, consulte <ulink url="help:/kate/kate-application-plugin-gdb.html"
>a documentação do plugin GDB</ulink
>.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>MarkBreakpointDisabled</userinput
> (<guilabel
>Ponto de parada desativado</guilabel
>)</term>
<listitem
><para
>Esta cor é usada pelo plugin GDB para indicar um ponto de parada inativo. Observe que esta cor tem opacidade em relação ao fundo. Para mais informações, consulte <ulink url="help:/kate/kate-application-plugin-gdb.html"
>a documentação do plugin GDB</ulink
>.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>MarkExecution</userinput
> (<guilabel
>Execução</guilabel
>)</term>
<listitem
><para
>Esta cor é usada pelo plugin GDB na linha que está sendo executada no momento. Observe que esta cor tem opacidade em relação ao fundo. Para mais informações, consulte <ulink url="help:/kate/kate-application-plugin-gdb.html"
>a documentação do plugin GDB</ulink
>.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>MarkWarning</userinput
> (<guilabel
>Aviso</guilabel
>)</term>
<listitem
><para
>Esta cor é usada pelo plugin de compilação para indicar uma linha que causou um aviso do compilador. Observe que esta cor tem opacidade em relação ao fundo. Para obter mais informações, consulte <ulink url="help:/kate/kate-application-plugin-build.html"
>a documentação do plugin de compilação</ulink
>.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>MarkError</userinput
> (<guilabel
>Erro</guilabel
>)</term>
<listitem
><para
>Esta cor é usada pelo plugin de compilação para indicar uma linha que causou um erro do compilador Observe que esta cor tem opacidade em relação ao fundo. Para obter mais informações, consulte <ulink url="help:/kate/kate-application-plugin-build.html"
>a documentação do plugin de compilação</ulink
>.</para
></listitem>
</varlistentry>

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

<varlistentry id="variable-prefcolors-colors-text-templates-snippets">
<term
><guilabel
>Modelos de texto e trechos</guilabel
></term>
<listitem>
<variablelist>

<varlistentry>
<term
><userinput
>TemplateBackground</userinput
> (<guilabel
>Fundo</guilabel
>)</term>
<listitem
><para
>Esta cor é usada pelo plugin de trechos do &kate; para marcar o fundo de um trecho de código. Para mais informações, consulte <ulink url="help:/kate/kate-application-plugin-snippets.html"
>a documentação de trechos do &kate;</ulink
>.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>TemplatePlaceholder</userinput
> (<guilabel
>Espaço reservado editável</guilabel
>)</term>
<listitem
><para
>Esta cor é usada pelo plugin de trechos do &kate; para marcar um espaço reservado que você pode clicar para editar manualmente. Para mais informações, consulte <ulink url="help:/kate/kate-application-plugin-snippets.html"
>a documentação de trechos do &kate;</ulink
>.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>TemplateFocusedPlaceholder</userinput
> (<guilabel
>Espaço reservado editável focado</guilabel
>)</term>
<listitem
><para
>Esta cor é usada pelo plugin de trechos do &kate; para marcar o espaço reservado que você está editando atualmente. Para mais informações, consulte <ulink url="help:/kate/kate-application-plugin-snippets.html"
>a documentação de trechos do &kate;</ulink
>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-Template.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>TemplateReadOnlyPlaceholder</userinput
> (<guilabel
>Espaço reservado não editável</guilabel
>)</term>
<listitem
><para
>Esta cor é usada pelo plugin de trechos do &kate; para marcar um espaço reservado que não pode ser editado manualmente, como o que é preenchido automaticamente. Para mais informações, consulte <ulink url="help:/kate/kate-application-plugin-snippets.html"
>a documentação de trechos do &kate;</ulink
>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-TemplateReadOnlyPlaceholder.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>

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

</variablelist>

</sect3>

<sect3 id="color-themes-text-styles">

<title
>Estilos de texto padrão</title>

<para
>Os estilos de texto padrão são herdados pelos estilos de texto realçados, permitindo ao editor apresentar o texto de forma bastante consistente. Por exemplo, o texto do comentário usa o mesmo estilo em quase todos os formatos de texto que o KSyntaxHighlighting  consegue realçar. </para>

<note>
<para
>Esses estilos de texto podem ser referenciados nos <userinput
>estilos padrão</userinput
> usados ​​nos arquivos de definição &XML; de <link linkend="highlight"
>realce de sintaxe</link
>. Por exemplo, o atributo <quote
>Normal</quote
> é equivalente a <quote
>dsNormal</quote
> nos arquivos &XML; e <quote
>DataType</quote
> é equivalente a <quote
>dsDataType</quote
>. Consulte <xref linkend="kate-highlight-default-styles"/> na documentação de realce de sintaxe. </para>
</note>

<tip>
<para
>Certifique-se de escolher cores legíveis com bom contraste, especialmente em combinação com as <userinput
><link linkend="color-themes-editor-colors"
>Cores do editor</link
></userinput
>. Consulte <xref linkend="color-themes-contrast"/>. </para>
</tip>

<para
>No <link linkend="color-themes-json"
>arquivo &JSON;</link
>, a chave <userinput
>text-styles</userinput
> respectiva tem como valor um <emphasis
>objeto</emphasis
> onde cada chave corresponde ao nome de um <emphasis
>estilo de texto padrão</emphasis
>, que são equivalentes aos usados ​​nas definições de realce de sintaxe. Aqui, <userinput
>todas as chaves de estilo de texto disponíveis são obrigatórias</userinput
>, e estão listadas abaixo. </para>

<programlisting
>"text-styles": {
    "Normal" : {
        "text-color" : "#1f1c1b",
        "selected-text-color" : "#ffffff",
        "bold" : false,
        "italic" : false,
        "underline" : false,
        "strike-through" : false
    },
    "Keyword" : {
        "text-color" : "#1f1c1b",
        "selected-text-color" : "#ffffff",
        "bold" : true
    },
    "Function" : {
        "text-color" : "#644a9b",
        "selected-text-color" : "#452886"
    },
    <replaceable
>As outras chaves de estilo de texto...</replaceable>
}
</programlisting>

<variablelist>
<varlistentry>

<term
>Cada chave de <emphasis
>estilo de texto padrão</emphasis
> possui um objeto &JSON; como seu valor, onde valores como <emphasis
>color</emphasis
>, <emphasis
>bold</emphasis
>, <emphasis
>italic</emphasis
>, etc. são especificados. Essas chaves são as seguintes: </term>

<listitem>

<para
><userinput
>text-color</userinput
>: É uma <emphasis
>string</emphasis
> com a cor do texto em código hexadecimal. Este par chave/valor é obrigatório.</para>

<para
><userinput
>selected-text-color</userinput
>: A cor do texto quando ele é selecionado geralmente tem o mesmo valor que <quote
>text-color</quote
>. Quando o texto é selecionado, o fundo é definido pelo valor de <link linkend="variable-pref-colors-selected-text"
>TextSelection</link
> em <link linkend="color-themes-editor-colors"
>Cores do editor</link
>, portanto, você deve garantir que o texto tenha bom contraste e seja legível com esse fundo. O valor é uma <emphasis
>string</emphasis
> com um código de cor hexadecimal. Este par chave/valor é obrigatório.</para>

<para
><userinput
>bold</userinput
>: É um <emphasis
>booleano</emphasis
> que determina se o texto está em negrito. Esta chave é opcional, o valor padrão é <userinput
>false</userinput
>.</para>

<para
><userinput
>italic</userinput
>: É um <emphasis
>booleano</emphasis
> que determina se o texto está em itálico. Esta chave é opcional, o valor padrão é <userinput
>false</userinput
>.</para>

<para
><userinput
>underline</userinput
>: É um <emphasis
>booleano</emphasis
> que determina se o texto está sublinhado. Esta chave é opcional, o valor padrão é <userinput
>false</userinput
>.</para>

<para
><userinput
>strike-through</userinput
>: É um <emphasis
>booleano</emphasis
> que determina se o texto está riscado. Esta chave é opcional, o valor padrão é <userinput
>false</userinput
>.</para>

<para
><userinput
>background-color</userinput
>: Determina a cor de fundo do texto, usada, por exemplo, em alertas e comentários. O valor é uma <emphasis
>string</emphasis
> com um código de cor hexadecimal. Esta chave é opcional; por padrão, não há cor de fundo.</para>

<para
><userinput
>selected-background-color</userinput
>: Determina a cor de fundo do texto quando ele é selecionado. O valor é uma <emphasis
>string</emphasis
> com um código de cor hexadecimal. Esta chave é opcional; por padrão, não há cor de fundo.</para>

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

<para
>Na <link linkend="color-themes-gui"
>&GUI; para gerenciar temas de cores do KTextEditor</link
>, esses atributos podem ser modificados na aba <userinput
><guilabel
>Estilos de texto padrão</guilabel
></userinput
>. O nome na lista de estilos usa o estilo configurado para o item, fornecendo uma pré-visualização imediata ao configurar um estilo. Cada estilo permite selecionar atributos comuns, bem como cores de primeiro plano e de fundo. Para remover uma cor de fundo, clique com o botão direito do mouse para usar o menu de contexto.</para>

<para
>As chaves de estilo de texto disponíveis são as seguintes; as chaves usadas no <link linkend="color-themes-json"
>arquivo &JSON;</link
> estão listadas em <emphasis
>negrito</emphasis
>, os nomes usados na <link linkend="color-themes-gui"
>&GUI;</link
> são mostrados entre parênteses se forem diferentes.</para>

<variablelist>
<varlistentry>
<term
><guilabel
>Texto normal e código-fonte</guilabel
></term>
<listitem>
<para
><userinput
>Normal</userinput
>: Estilo de texto padrão para texto normal e código-fonte sem realce especial.</para>

<para
><userinput
>Keyword</userinput
>: Estilo de texto para palavras-chave de linguagem integradas.</para>

<para
><userinput
>Function</userinput
>: Estilo de texto para definições de função e chamadas de função.</para>

<para
><userinput
>Variable</userinput
>: Estilo de texto para variáveis, se aplicável. Por exemplo, variáveis ​​em PHP/Perl normalmente começam com um <userinput
>$</userinput
>, portanto, todos os identificadores que seguem o padrão <userinput
>$foo</userinput
> são destacados como variáveis.</para>

<para
><userinput
>ControlFlow</userinput
> (<guilabel
>Fluxo de controle</guilabel
>): Estilo de texto para palavras-chave de fluxo de controle, como <emphasis
>if</emphasis
>, <emphasis
>then</emphasis
>, <emphasis
>else</emphasis
>, <emphasis
>return</emphasis
>, <emphasis
>switch</emphasis
>, <emphasis
>break</emphasis
>, <emphasis
>yield</emphasis
>, <emphasis
>continue</emphasis
>, etc.</para>

<para
><userinput
>Operator</userinput
>: Estilo de texto para operadores, como <userinput
>+</userinput
>, <userinput
>-</userinput
>, <userinput
>*</userinput
>, <userinput
>/</userinput
>, <userinput
>%</userinput
>, etc.</para>

<para
><userinput
>BuiltIn</userinput
> (<guilabel
>Integrado</guilabel
>): Estilo de texto para classes de linguagem, funções e objetos integrados.</para>

<para
><userinput
>Extension</userinput
>: Estilo de texto para extensões conhecidas, como classes &Qt;, funções/macros em C++ e Python ou boost.</para>

<para
><userinput
>Preprocessor</userinput
>: Estilo de texto para instruções do pré-processador ou definições de macro.</para>

<para
><userinput
>Attribute</userinput
>: Estilo de texto para anotações ou atributos de funções ou objetos, por exemplo, <userinput
>@override</userinput
> em Java, ou <userinput
>__declspec(...)</userinput
> e <userinput
>__attribute__((...))</userinput
> em C++.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><guilabel
>Números, tipos e constantes</guilabel
></term>
<listitem>
<para
><userinput
>DataType</userinput
> (<guilabel
>Tipo de dados</guilabel
>): Estilo de texto para tipos de dados integrados como <emphasis
>int</emphasis
>, <emphasis
>char</emphasis
>, <emphasis
>float</emphasis
>, <emphasis
>void</emphasis
>, <emphasis
>u64</emphasis
>, etc.</para>

<para
><userinput
>DecVal</userinput
> (<guilabel
>Decimal/Valor</guilabel
>): Estilo de texto para valores decimais.</para>

<para
><userinput
>BaseN</userinput
> (<guilabel
>Inteiro de base N</guilabel
>): Estilo de texto para números com base diferente de 10.</para>

<para
><userinput
>Float</userinput
> (<guilabel
>Ponto flutuante</guilabel
>): Estilo de texto para números de ponto flutuante.</para>

<para
><userinput
>Constant</userinput
>: Estilo de texto para constantes de linguagem e constantes definidas pelo usuário, por exemplo, <emphasis
>True</emphasis
>, <emphasis
>False</emphasis
>, <emphasis
>None</emphasis
> em Python ou <emphasis
>nullptr</emphasis
> em C/C++; ou constantes matemáticas como <emphasis
>PI</emphasis
>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><guilabel
>Strings e caracteres</guilabel
></term>
<listitem>
<para
><userinput
>Char</userinput
> (<guilabel
>Caractere</guilabel
>): Estilo de texto para caracteres únicos como <userinput
>'x'</userinput
>.</para>

<para
><userinput
>SpecialChar</userinput
> (<guilabel
>Caractere especial</guilabel
>): Estilo de texto para caracteres escapados em strings, por exemplo, <quote
><userinput
>olá\n</userinput
></quote
>, e outros caracteres com significado especial em strings, como substituições ou operadores regex.</para>

<para
><userinput
>String</userinput
>: Estilo de texto para strings como <quote
><userinput
>olá mundo</userinput
></quote
>.</para>

<para
><userinput
>VerbatimString</userinput
> (<guilabel
>String Verbatim</guilabel
>): Estilo de texto para strings literais ou brutas como <userinput
>'raw\backlash'</userinput
> em Perl, CoffeeScript e shells, bem como <userinput
>r'\raw'</userinput
> em Python, ou como na documentação AQUI.</para>

<para
><userinput
>SpecialString</userinput
> (<guilabel
>String especial</guilabel
>): Estilo de texto para strings especiais, como expressões regulares em ECMAScript, o modo matemático &latex;, SQL, etc.</para>

<para
><userinput
>Import</userinput
> (<guilabel
>Importações, Módulos, Inclusões</guilabel
>): Estilo de texto para inclusões, importações, módulos ou pacotes &latex;.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><guilabel
>Comentários e documentação</guilabel
></term>
<listitem>
<para
><userinput
>Comment</userinput
>: Estilo de texto para comentários normais.</para>

<para
><userinput
>Documentation</userinput
>: Estilo de texto para comentários que refletem a documentação da API, como <userinput
>/** comentários doxygen */</userinput
> ou <userinput
>"""docstrings"""</userinput
>.</para>

<para
><userinput
>Annotation</userinput
>: Estilo de texto para anotações em comentários ou comandos de documentação, como <userinput
>@param</userinput
> em Doxygen ou JavaDoc.</para>

<para
><userinput
>CommentVar</userinput
> (<guilabel
>Variável de comentário</guilabel
>): Estilo de texto que se refere aos nomes das variáveis ​​usadas nos comandos acima em um comentário, como <userinput
>foobar</userinput
> em <quote
><userinput
>@param foobar</userinput
></quote
>, no Doxygen ou JavaDoc.</para>

<para
><userinput
>RegionMarker</userinput
> (<guilabel
>Marcador de região</guilabel
>): Estilo de texto para marcadores de região, normalmente definido por <userinput
>//BEGIN</userinput
> e <userinput
>//END</userinput
> em comentários.</para>

<para
><userinput
>Information</userinput
>: Estilo de texto para informações, notas e dicas, como a palavra-chave <userinput
>@note</userinput
> no Doxygen.</para>

<para
><userinput
>Warning</userinput
>: Estilo de texto para avisos, como a palavra-chave <userinput
>@warning</userinput
> no Doxygen.</para>

<para
><userinput
>Alert</userinput
>: Estilo de texto para palavras especiais em comentários, como <userinput
>TODO</userinput
>, <userinput
>FIXME</userinput
>, <userinput
>XXXX</userinput
> e <userinput
>WARNING</userinput
>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><guilabel
>Diversos</guilabel
></term>
<listitem>
<para
><userinput
>Error</userinput
>: Estilo de texto indicando realce de erro e sintaxe incorreta.</para>

<para
><userinput
>Others</userinput
>: Estilo de texto para atributos que não correspondem a nenhum dos outros estilos padrão.</para>
</listitem>
</varlistentry>
</variablelist>

</sect3>

<sect3 id="color-themes-custom-styles">

<title
>Estilos de texto de realce personalizados</title>

<para
>Aqui você pode definir estilos de texto para uma definição específica de realce de sintaxe, substituindo o <userinput
>estilo de texto padrão</userinput
> descrito na <link linkend="color-themes-text-styles"
>seção anterior</link
>. </para>

<para
>No <link linkend="color-themes-json"
>arquivo de tema &JSON;</link
>, isso corresponde à chave <userinput
>custom-styles</userinput
>, cujo valor é um <emphasis
>objeto</emphasis
> onde cada chave de subesquema corresponde ao <userinput
>nome de uma definição de realce de sintaxe</userinput
>. Seu valor é um <emphasis
>objeto</emphasis
> onde cada chave se refere ao <userinput
>nome dos atributos de estilo</userinput
> definidos nos <link linkend="kate-highlight-sections"
>elementos <userinput
>itemData</userinput
></link
> do arquivo de realce de sintaxe &XML;, e o respectivo valor é um subobjeto com as chaves <emphasis
>text-color</emphasis
>, <emphasis
>selected-text-color</emphasis
>, <emphasis
>bold</emphasis
>, <emphasis
>italic</emphasis
>, <emphasis
>underline</emphasis
>, <emphasis
>strike-through</emphasis
>, <emphasis
>background-color</emphasis
> e <emphasis
>selected-background-color</emphasis
>, definidas <link linkend="color-themes-text-styles"
>na seção anterior</link
>. Cada um desses valores é opcional, pois se eles não estiverem presentes, o estilo definido em <userinput
>text-styles</userinput
> é considerado. </para>

<para
>Por exemplo, neste trecho de código, a definição de realce de sintaxe <quote
>ISO C++</quote
> tem um estilo de texto especial para os atributos <quote
>Type Modifiers</quote
> e <quote
>Standard Classes</quote
>. No arquivo &XML; correspondente <quote
>isocpp.xml</quote
>, o atributo definido <quote
>Standard Classes</quote
> usa o estilo padrão <userinput
>BuiltIn</userinput
> (ou dsBuiltIn). Neste atributo, apenas o valor de <userinput
>text-color</userinput
> é sobrescrito pela nova cor <quote
>#6431b3</quote
>. </para>

<programlisting
>"custom-styles": {
    "ISO C++": {
        "Standard Classes": {
            "text-color": "#6431b3"
        },
        "Type Modifiers": {
            "bold": true,
            "selected-text-color": "#009183",
            "text-color": "#00b5cf"
        }
    }
}
</programlisting>

<note>
<itemizedlist>

<listitem>
<para
>Você deve levar em consideração que esses estilos de texto estão associados aos nomes de atributos definidos nos arquivos de realce de sintaxe &XML;. Se um arquivo XML for atualizado e alguns atributos forem renomeados ou removidos, o estilo personalizado definido no tema deixará de ser aplicado.</para>
</listitem>

<listitem>
<para
>As definições de realce de sintaxe frequentemente incluem outras definições. Por exemplo, o realçador de sintaxe <quote
>QML</quote
> inclui o realçador de sintaxe <quote
>JavaScript</quote
>, já que compartilham funcionalidades de realce.</para>
</listitem>

</itemizedlist>
</note>

<para
>Na <link linkend="color-themes-gui"
>&GUI; para gerenciar temas do KTextEditor</link
>, esses atributos podem ser modificados na aba <userinput
><guilabel
>Estilos de realce de texto</guilabel
></userinput
>. Por padrão, o editor pré-seleciona o realce do documento atual. Você notará que muitos realces contêm outros realces representados por grupos na lista de estilos. Por exemplo, a maioria dos realces importa o realce <quote
>Alerta</quote
> e muitos formatos de código-fonte importam o realce <quote
>Doxygen</quote
>. </para>

</sect3>

</sect2>

<sect2 id="color-themes-gui">

<title
>&GUI; dos temas de cores</title>

<para
>A maneira mais simples de criar e editar temas de cores é através da &GUI; dentro da <link linkend="config-dialog"
>janela <quote
>Configurar</quote
></link
> fornecida pelo <ulink url="https://api.kde.org/frameworks/ktexteditor/html/"
>KTextEditor</ulink
>. Para acessá-la, selecione <menuchoice
><guimenu
>Configurações</guimenu
> <guimenuitem
>Configurar <replaceable
>aplicativo</replaceable
>...</guimenuitem
></menuchoice
> na barra de menus do seu editor de texto. Isso abrirá a janela <guilabel
>Configurar</guilabel
>, onde você poderá selecionar <guilabel
>Temas de cores</guilabel
> no painel lateral. </para>

<mediaobject>
<imageobject
><imagedata format="PNG" fileref="color-themes-gui-default-text-styles.png"/></imageobject>
<textobject
><phrase
>Janela de configuração do &kate; com o gerenciamento de temas de cores.</phrase
></textobject>
<caption
><para
>Janela de configuração do &kate; com o gerenciamento de temas de cores.</para>
</caption>
</mediaobject>

<para
>Nesta <link linkend="config-dialog"
>janela</link
> você pode configurar todas as cores de qualquer tema que você tenha, bem como criar/copiar novos temas, excluí-los, exportá-los para um arquivo <userinput
>.theme</userinput
> com <link linkend="color-themes-json"
>formato &JSON;</link
> ou importá-los de arquivos <userinput
>.theme</userinput
> externos. Cada tema possui configurações para cores e estilos de texto. </para>

<para
>Os temas integrados não podem ser modificados por padrão. Para fazer isso, você precisa copiá-los e dar-lhes um novo nome.</para>

<para
>Para usar um tema permanentemente em seu editor de texto, você deve selecioná-lo na caixa de combinação rotulada como <guilabel
>Tema padrão para <replaceable
>aplicativo</replaceable
></guilabel
> na parte inferior da janela e pressionar <guibutton
>Aplicar</guibutton
> ou <guibutton
>OK</guibutton
>. Por padrão, a opção <userinput
><guilabel
>Seleção automática</guilabel
></userinput
> está ativa, que escolhe um tema de cores mais apropriado de acordo com o <emphasis
>esquema de cores do &kde; &plasma;</emphasis
> usado no aplicativo de edição de texto; geralmente, escolhe entre <quote
>Breeze Light</quote
> e <quote
>Breeze Dark</quote
> se o esquema for claro ou escuro, respectivamente. </para>

<tip>
<para
>Você pode ajustar o esquema de cores global do &kde; no <ulink url="help:/kcontrol/colors/"
>módulo <quote
>Cores</quote
> nas &systemsettings;</ulink
>. Você também pode alterá-lo individualmente em alguns aplicativos, como o &kate; ou o &kdevelop;, no menu <menuchoice
><guimenu
>Configurações</guimenu
><guisubmenu
>Esquema de cores</guisubmenu
></menuchoice
>. </para>
</tip>

<sect3 id="color-themes-gui-new-theme">

<title
>Criar um novo tema</title>

<para
>Para criar um novo tema, primeiro é necessário copiar um existente. Selecione um tema existente que você deseja usar como base, como <quote
>Breeze Light</quote
> ou <quote
>Breeze Dark</quote
>, e clique em <guibutton
>Copiar</guibutton
>. Em seguida, digite um nome para o novo tema. </para>

<para
>Se você quiser modificar um tema integrado ou somente leitura, primeiro você deve copiá-lo com um nome diferente.</para>

</sect3>

<sect3 id="color-themes-gui-import-export">

<title
>Importar ou exportar arquivos de tema &JSON;</title>

<para
>Você pode exportar um tema selecionado (incluindo os temas integrados) para um <link linkend="color-themes-json"
>arquivo &JSON;</link
> com a extensão <userinput
>.theme</userinput
>, usando o botão <guibutton
>Exportar</guibutton
>. Isso abrirá uma janela para salvar o arquivo. Para adicionar um tema de cores de um <link linkend="color-themes-json"
>arquivo &JSON;</link
> externo, basta pressionar o botão <guibutton
>Importar</guibutton
> e selecionar o arquivo <userinput
>.theme</userinput
> na janela. </para>

<tip>
<itemizedlist>

<listitem>
<para
>Como <link linkend="color-themes-json-overview"
>mencionado acima</link
>, os arquivos de tema personalizados pelo usuário são armazenados na pasta <filename class="directory"
>org.kde.syntax-highlighting/themes/</filename
>. Ao copiar ou criar um tema, ele aparecerá automaticamente lá. Além disso, importar ou adicionar um tema é equivalente a copiar um arquivo <userinput
>.theme</userinput
> externo para esta pasta. O KSyntaxHighlighting detecta automaticamente os arquivos de tema de cores desta pasta.</para>
</listitem>

<listitem>
<para
>Se você deseja publicar um tema criado por você, é essencial verificar o objeto <link linkend="color-themes-json-metadata"
>metadata</link
> do <link linkend="color-themes-json"
>arquivo &JSON;</link
>, adicionando a licença respectiva e verificando o número da revisão.</para>
</listitem>

</itemizedlist>
</tip>

</sect3>

<sect3 id="color-themes-gui-editing">

<title
>Editando temas de cores</title>

<sect4 id="prefcolors-colors">

<title
>Cores</title>

<para
>Aqui, as cores da área de edição de texto são ajustadas. Elas são detalhadas em <xref linkend="color-themes-editor-colors"/>.</para>

</sect4>

<sect4 id="prefcolors-normal-text-styles">

<title
>Estilos de texto padrão</title>

<para
>Os estilos de texto padrão são herdados pelos estilos de texto realçados, permitindo ao editor apresentar o texto de forma bastante consistente. Por exemplo, o texto do comentário usa o mesmo estilo em quase todos os formatos de texto que o KSyntaxHighlighting  consegue realçar.</para>
<para
>O nome na lista de estilos está usando o estilo configurado para o item, oferecendo-lhe uma visualização imediata ao configurar um estilo. </para>
<para
>Cada estilo permite selecionar atributos comuns, bem como cores de primeiro plano e de fundo. Para remover uma cor de fundo, clique com o botão direito do mouse para usar o menu de contexto.</para>
<para
>Os atributos desta área estão detalhados em <xref linkend="color-themes-text-styles"/>.</para>

</sect4>

<sect4 id="prefcolors-highlighting-text-styles">

<title
>Estilos de texto de realce</title>

<para
>Aqui você poderá editar os estilos de texto usados por uma definição de realce específica. O editor seleciona previamente o realce usado pelo seu documento atual. Para funcionar com um realce diferente, selecione um na lista <guilabel
>Realce</guilabel
>, acima da lista de estilos. </para>
<para
>O nome na lista de estilos está usando o estilo configurado para o item, oferecendo-lhe uma visualização imediata ao configurar um estilo. </para>
<para
>Cada estilo permite-lhe selecionar os atributos comuns, assim como as cores de fundo e do texto. Para retirar uma cor de fundo, clique com o botão direito para usar o menu de contexto. Além disso, você poderá verificar se um estilo é igual ao pré-definido que for usado para o item, e configurá-lo como tal, se não estiver.</para>
<para
>Você notará que vários realces contém outros realces, representados por grupos na lista de estilos. Por exemplo, a maioria dos realces implementam o realce Alert (Alerta) e muitos formatos de código importam o realce do Doxygen. A edição das cores destes grupos só afetará os estilos se forem usados no formato de realce editado. </para>

</sect4>

</sect3>

</sect2>

<sect2 id="color-themes-tips-and-tricks">

<title
>Dicas &amp; Truques</title>

<sect3 id="color-themes-contrast">

<title
>Contraste das cores do texto</title>

<para
>Um aspecto importante ao trabalhar com temas de cores é escolher um contraste de texto que facilite a leitura, especialmente em combinação com o fundo.</para>

<para
>O aplicativo <userinput
>Kontrast</userinput
> é um verificador de contraste de cores. Ele informa se as combinações de cores de texto e de fundo são legíveis e acessíveis, sendo uma excelente ferramenta para ajudar na criação de temas de cores.</para>

<para
>Você pode baixar o <userinput
>Kontrast</userinput
> do <ulink url="https://apps.kde.org/en/kontrast"
>site de aplicativos do &kde;</ulink
> ou do <ulink url="https://flathub.org/apps/details/org.kde.kontrast"
>pacote Flatpak no Flathub</ulink
> (somente para GNU/Linux).</para>

<para
>O aplicativo <userinput
>Contrast</userinput
> do GNOME é semelhante. Você pode baixar <ulink url="https://flathub.org/apps/details/org.gnome.design.Contrast"
>o pacote Flatpak no Flathub</ulink
> (somente para GNU/Linux).</para>

<para
>Um script Python no <ulink url="https://invent.kde.org/frameworks/syntax-highlighting/-/blob/master/utils/theme_contrast_checker.py?ref_type=heads"
>Repositório de realce de sintaxe</ulink
> permite visualizar todas as cores em um tema, bem como o contraste com os vários planos de fundo configurados.</para>

</sect3>

<sect3 id="color-themes-tips-and-tricks-consistency">

<title
>Sugestões de consistência com o realce de sintaxe</title>

<para
>O KSyntaxHighlighting inclui <ulink url="https://kate-editor.org/syntax/"
>mais de 300 definições de realce de sintaxe</ulink
>, portanto, é ideal que você se certifique de que seu novo tema fique bem em todas as definições de realce de sintaxe. Os temas de cores integrados têm as seguintes semelhanças que é recomendável (mas não obrigatório) seguir para obter uma exibição correta de todas as definições de realce de sintaxe:</para>

<itemizedlist>
<listitem
><para
>Use negrito para os <link linkend="color-themes-text-styles"
>estilos de texto</link
> <quote
>Keyword</quote
> e <quote
>ControlFlow</quote
>.</para
></listitem>

<listitem
><para
>Não use cor de fundo em qualquer <link linkend="color-themes-text-styles"
>estilo de texto</link
>, exceto <quote
>Alert</quote
> e <quote
>RegionMarker</quote
>.</para
></listitem>
</itemizedlist>

<para
>A maioria dos realçadores de sintaxe são projetados para ter uma boa aparência nos temas padrão <quote
>Breeze Light</quote
> e <quote
>Breeze Dark</quote
>, portanto, outra maneira de manter a consistência é usar cores semelhantes nos <link linkend="color-themes-text-styles"
>estilos de texto</link
>, como <emphasis
>verde</emphasis
> para <quote
>Preprocessor</quote
> e <quote
>Others</quote
>, <emphasis
>azul</emphasis
> para <quote
>DataType</quote
> e <quote
>Attribute</quote
>, ou <emphasis
>roxo</emphasis
> para <quote
>Function</quote
>.</para>

<para
>Observe que essas recomendações não são obrigatórias ao criar e publicar um tema.</para>

</sect3>

</sect2>

</sect1>


<sect1 id="dev-scripting">
<title
>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. Uma funcionalidade semelhante aos scripts de linha de comando também é fornecida no <ulink url="help:/kate/kate-application-plugin-snippets.html"
>plugin de trechos</ulink
>. </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, &eg;, <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>
<para
>No &Windows; estes arquivos estão localizados em <filename
>%USERPROFILE%\AppData\Local\katepart5\script\indentation</filename
>. <replaceable
>%USERPROFILE%</replaceable
> que normalmente se expandem para <filename
>C:\\Users\\<replaceable
>usuário</replaceable
></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 &lt;nome.exemplo@endereco.org&gt;",
    "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, &eg;: <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, &eg; 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
>Formatar recuo</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 &gt;= 0 definem a largura do recuo em espaços</para
></listitem
> </itemizedlist
> Em alternativa, poderá ser devolvida uma lista com dois elementos: <itemizedlist
> <listitem
><para
><literal
>return [ recuo, alinhamento ];</literal
></para
></listitem
> </itemizedlist
> Nesse caso, o primeiro elemento é a profundidade de recuo, tendo o mesmo significado que os valores especiais. Contudo, o segundo elemento é um valor absoluto que representa uma coluna para o <quote
>alinhamento</quote
>. Se este valor for maior que o valor do recuo, a diferença representa um número de espaços a adicionar após o recuo do primeiro parâmetro. Caso contrário, o segundo número será ignorado. A utilização de tabulações e espaços nos recuos é normalmente referida como sendo um <quote
>modo misto</quote
>. </para>

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

<para
>Uma instalação padrão do &kde; fornece o &kappname; com vários módulos de recuo. O código-fonte correspondente em &javascript; poderá ser encontrado em <filename
>$<envar
>XDG_DATA_DIRS</envar
>/katepart5/script/indentation</filename
>.</para>
<para
>No &Windows; estes arquivos estão localizados em <filename
>%USERPROFILE%\AppData\Local\katepart5\script\indentation</filename
>. <replaceable
>%USERPROFILE%</replaceable
> que normalmente se expandem para <filename
>C:\\Users\\<replaceable
>usuário</replaceable
></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; enviando uma solicitação de mesclagem para <ulink url="https://invent.kde.org/frameworks/ktexteditor"
>nosso projeto no GitLab</ulink
>. </para>

</sect3>
</sect2>

<sect2 id="dev-scripting-command-line">
<title
>Scripts de Linha de Comando</title>

<note>
<para
>Uma funcionalidade semelhante a scripts de linha de comando também é fornecida no <ulink url="help:/kate/kate-application-plugin-snippets.html"
>plugin de trechos</ulink
>. Este plugin pode fornecer um ponto de partida mais fácil, especialmente para pequenos scripts personalizados.</para>
</note>

<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>
<para
>No Windows, esses arquivos estão localizados em <filename
>%USERPROFILE%\AppData\Local\katepart5\script\commands</filename
>. <replaceable
>%USERPROFILE%</replaceable
> geralmente se expande para <filename
>C:\\Users\\<replaceable
>usuário</replaceable
></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 &lt;nome.exemplo@endereco.org&gt;",
    "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]: Array 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, &eg; range.js se você usar Range
function &lt;nome&gt;(arg1, arg2, ...)
{
    // ... implementação, ver também: API de Programação
}
</programlisting>
</para>

<para
>Os argumentos na linha de comando são passados à função como <parameter
>arg1</parameter
>, <parameter
>arg2</parameter
>, &etc; Para poder indicar a documentação de cada comando, basta implementar a função '<function
>help</function
>', como demonstrado a seguir: <programlisting>
function help(cmd)
{
    if (cmd == "sort") {
        return i18n("Ordena o texto selecionado.");
    } else if (cmd == "...") {
        // ...
    }
}
</programlisting
> Executar <command
>help sort</command
> na linha de comando, irá invocar esta função de ajuda com o argumento <parameter
>cmd</parameter
> igual ao comando indicado, 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="https://doc.qt.io/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; enviando uma solicitação de mesclagem para <ulink url="https://invent.kde.org/frameworks/ktexteditor"
>nosso projeto no GitLab</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, &eg; 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
>No Windows, esses arquivos estão localizados em <filename
>%USERPROFILE%\AppData\Local\katepart5\libraries</filename
>. <replaceable
>%USERPROFILE%</replaceable
> geralmente se expande para <filename
>C:\\Users\\<replaceable
>usuário</replaceable
></filename
>.</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
>katepart5/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
>katepart5/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="https://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
>void view.copy()</function
>
</synopsis
></term>
<listitem>
<para
>Copia a seleção se houver uma, caso contrário, a linha atual se a opção <userinput
>[ ] Copiar/Recortar a linha atual se nenhuma seleção</userinput
> estiver definida.</para>
<para
>Desde: &kde-frameworks; 5.79</para>
</listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
><function
>void view.cut()</function
>
</synopsis
></term>
<listitem>
<para
>Recorta a seleção se houver uma, caso contrário, a linha atual se a opção <userinput
>[ ] Copiar/Recortar a linha atual se nenhuma seleção</userinput
> estiver definida.</para>
<para
>Desde: &kde-frameworks; 5.79</para>
</listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
><function
>void view.paste()</function
>
</synopsis
></term>
<listitem>
<para
>Cola o conteúdo da área de transferência.</para>
<para
>Desde: &kde-frameworks; 5.79</para>
</listitem>
</varlistentry>


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


<varlistentry>
<term
><synopsis
>void view.setBlockSelection(bool on);
</synopsis
></term>
<listitem
><para
>Liga/desliga o modo de seleção de blocos. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>bool view.blockSelection();
</synopsis
></term>
<listitem
><para
>Devolve <literal
>true</literal
> (verdadeiro) se o modo de seleção de bloco estiver ligado, caso contrário, devolve <literal
>false</literal
> (falso). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void view.align(<parameter
>Range <replaceable
>intervalo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Ajusta corretamente o recuo das linhas dentro do <replaceable
>intervalo</replaceable
> de acordo com as configurações de recuo atuais. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>void view.alignOn(<parameter
>Range <replaceable
>intervalo</replaceable
></parameter
>, <parameter
>String <replaceable
>padrão</replaceable
> = &quot;&quot;</parameter
>);
</synopsis
></term>
<listitem
><para
>Alinha as linhas no <replaceable
>intervalo</replaceable
> na coluna especificada pela expressão regula <replaceable
>padrão</replaceable
>. Com um <replaceable
>padrão</replaceable
> vazio especificado, o alinhamento será feito no primeiro caractere não vazio. Se o padrão contiver uma captura, o recuo será feito na correspondência capturada. </para>
<para
><emphasis
>Exemplos:</emphasis
></para>
<para
><literal
>view.alignOn(document.documentRange(), '-');</literal
> irá inserir espaços antes do primeiro <literal
>-</literal
> de cada linha para alinhá-las todas na mesma coluna.</para>
<para
><literal
>view.alignOn(document.documentRange(), ':\\s+(.)');</literal
> Irá inserir espaços antes do primeiro caractere não em branco que ocorrer após dois pontos para alinhá-los todos na mesma coluna.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>object view.executeCommand(<parameter
>String <replaceable
>comando</replaceable
></parameter
>,
                           <parameter
>String <replaceable
>args</replaceable
></parameter
>,
                           <parameter
>Range <replaceable
>intervalo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Executa o <link linkend="advanced-editing-tools-commandline"
>comando de linha de comando</link
> <replaceable
>comando</replaceable
> com os argumentos opcionais <replaceable
>args</replaceable
> e o intervalo opcional <replaceable
>intervalo</replaceable
>. O objeto retornado <replaceable
>object</replaceable
> possui uma propriedade booleana <replaceable
>object.ok</replaceable
> que indica se a execução do comando <replaceable
>comando</replaceable
> foi bem-sucedida. Em caso de erro, a string <replaceable
>object.status</replaceable
> contém uma mensagem de erro. </para>
<para
>Desde: &kde-frameworks; 5.50</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>Range view.searchText(<parameter
>Range <replaceable
>intervalo</replaceable
></parameter
>,
                      <parameter
>String <replaceable
>padrão</replaceable
></parameter
>,
                      <parameter
>bool <replaceable
>backwards</replaceable
> = false</parameter
>);
</synopsis
></term>
<listitem
><para
>Busca a primeira ocorrência do <replaceable
>padrão</replaceable
> em <replaceable
>intervalo</replaceable
> e retorna o intervalo correspondente. A busca é realizada de trás para frente se o parâmetro booleano opcional <replaceable
>backwards</replaceable
> estiver definido como <literal
>true</literal
>. </para>
<para
>O intervalo retornado é inválido (consulte Range.isValid()) se <replaceable
>padrão</replaceable
> não for encontrado no <replaceable
>intervalo</replaceable
>. </para>
<para
>Desde: &kde-frameworks; 5.97</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 &MIME; <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, &eg;, a linha &lt; 0. </para>
<para
>Desde: &kde; 4.9 </para>
</listitem>
</varlistentry>


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


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


<varlistentry>
<term
><synopsis
>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>

<varlistentry>
<term
><synopsis
>void document.indent(<parameter
>Range <replaceable
>intervalo</replaceable
></parameter
>, <parameter
>int <replaceable
>número</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Recua todas as linhas em <replaceable
>intervalo</replaceable
> por <replaceable
>número</replaceable
> de tabulações ou <replaceable
>número</replaceable
> vezes <literal
>tabSize</literal
> espaços, dependendo das preferências do usuário. O parâmetro <replaceable
>número</replaceable
> pode ser negativo. </para
></listitem>
</varlistentry>

</variablelist>
</para>

</sect3>

<sect3 id="dev-scripting-api-editor">
<title
>A API do editor</title>
<para
>Além da API de documento e visualização, existe uma API de editor geral que fornece funções para funcionalidades gerais de script do editor. <variablelist>

<varlistentry>
<term
><synopsis
>String editor.clipboardText();
</synopsis
></term>
<listitem
><para
>Retorna o texto que está atualmente na área de transferência global. </para>
<para
>Desde: &kde-frameworks; 5.50</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>String editor.clipboardHistory();
</synopsis
></term>
<listitem
><para
>O editor mantém um histórico da área de transferência que contém até 10 entradas. Esta função retorna todas as entradas que estão atualmente no histórico da área de transferência. </para>
<para
>Desde: &kde-frameworks; 5.50</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>void editor.setClipboardText(<parameter
>String <replaceable
>texto</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Define o conteúdo da área de transferência para <replaceable
>texto</replaceable
>. O <replaceable
>texto</replaceable
> será adicionado ao histórico da área de transferência. </para>
<para
>Desde: &kde-frameworks; 5.50</para>
</listitem>
</varlistentry>

</variablelist>
</para>
</sect3>
</sect2>

</sect1>

</chapter>
