# Ampliando o &katepart;

## Introdução

Como em qualquer componente de editor de texto avançado, o &katepart; oferece uma grande variedade de formas para ampliar suas funcionalidades. Você pode criar scripts simples para adicionar funcionalidades com o &javascript; Finalmente, assim que tiver ampliado as funcionalidades do &katepart;, sinta-se a vontade para se juntar a nós e compartilhar as suas melhorias com o mundo!

## Trabalhando com Realce de Sintaxe

### Introdução

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.

Uma função C++, representada com realce de sintaxe.

Uma função C++, representada com realce de sintaxe.

A mesma função C++, sem realce de sintaxe.

A mesma função C++, sem realce de sintaxe.

Dos dois exemplos, qual é o mais fácil de ler?

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.

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 Ferramentas Realçar.

Os estilos e cores usados por cada definição de realce de sintaxe podem ser configurados usando a página de Estilos de Realce de Texto da Janela de Configuração; 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 Modos & Tipos de Arquivo.

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.

### O Sistema de Realce de Sintaxe do &kappname;

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.

#### Como funciona

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.

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.

As definições de sintaxe usadas pelo sistema de realce de sintaxe do &kappname; são arquivos &XML; que contém

- Regras para a detecção do texto inteiro, organizado em blocos de contexto

- Listas de palavras-chave

- Definições de Item de Estilo

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.

#### Regras

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 expressão regular 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.

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.

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.

#### Estilos de Contexto e Palavras-Chave

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.

Uma definição de sintaxe pode conter tantos estilos quanto forem necessários para cobrir os conceitos do formato no qual serão usados.

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.

#### Estilos Padrão

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.

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.

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 estilos padrão disponíveis serão explicados mais tarde.

### O Formato &XML; de Definição de Realce

#### Introdução

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.

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.

A definição formal, também conhecida como XSD, você encontra no Repositório de realce de sintaxe no arquivo `language.xsd`

Os arquivos de definição de realce personalizados `.xml` estão localizados em `org.kde.syntax-highlighting/syntax/` na sua pasta de usuário, encontrada com ``qtpaths``--paths GenericDataLocation`` que geralmente são ``$HOME`/.local/share/` e `/usr/share/`.

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 é ``$HOME`/.var/app/`nome-pacote-flatpak`/data/org.kde.syntax-highlighting/syntax/` e em um aplicativo Snap, esse local é ``$HOME`/snap/`nome-pacote-snap`/current/.local/share/org.kde.syntax-highlighting/syntax/`.

No Windows, esses arquivos estão localizados em `%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\syntax`. `%USERPROFILE%` geralmente se expande para `C:\Users\`user``.

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

Para o usuário local | ``$HOME`/.local/share/org.kde.syntax-highlighting/syntax/`
Para todos os usuários | `/usr/share/org.kde.syntax-highlighting/syntax/`
Para pacotes Flatpak | ``$HOME`/.var/app/`nome-pacote-flatpak`/data/org.kde.syntax-highlighting/syntax/`
Para pacotes Snap | ``$HOME`/snap/`nome-pacote-snap`/current/.local/share/org.kde.syntax-highlighting/syntax/`
No &Windows; | `%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\syntax`
No &macOS; | ``$HOME`/Library/Application Support/org.kde.syntax-highlighting/syntax/`

Se existirem vários arquivos para a mesma linguagem, o arquivo com o atributo de versão mais alto no elemento `language` será carregado.

#### Seções principais dos arquivos de Definições de Realce do &kappname;

Um arquivo de realce contém um cabeçalho que define a versão do &XML;:

-     <?xml version="1.0" encoding="UTF-8"?>

A raiz do arquivo de definição é o elemento `language`. Os atributos disponíveis são:

- Atributos necessários:

  O `name` define o nome da linguagem. Ele aparece nos respectivos menus e janelas.

  O `section` indica a categoria.

  O `extensions` define as extensões dos arquivos, como por exemplo, "*.cpp;*.h"

  O `version` 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.

  O `kateversion` indica a última versão suportada pelo &kappname;.

  Atributos opcionais:

  O `mimetype` associa os arquivos do tipo &MIME;.

  O `casesensitive` define se as palavras-chave fazem distinção entre maiúsculas e minúsculas.

  O `priority` é necessário se outro arquivo de definições de realce usar as mesmas extensões. Ganhará o que tiver maior prioridade.

  O `author` contém o nome do autor e o seu endereço de e-mail.

  O `license` contém a licença, que é normalmente a licença MIT para novos arquivos de realce de sintaxe.

  O `style` contém a linguagem fornecida e é usado pelos sistemas de recuo para o atributo `required-syntax-style`.

  O `indenter` define qual indentador será usado por padrão. Os indentadores disponíveis são: ada, normal, cstyle, cmake, haskell, latex, lilypond, lisp, lua, pascal, python, replicode, ruby e xml.

  O `hidden` define se o nome deverá aparecer nos menus do &kappname;.

  Assim, a próxima linha se parece com o seguinte:

      <language name="C++" version="1" kateversion="2.4" section="Sources" extensions="*.cpp;*.h" />

A seguir vem o elemento `highlighting`, que contém o elemento opcional `list` e os elementos obrigatórios `contexts` e `itemDatas`.

- O elemento `list` contém uma lista de palavras-chave. Neste caso, as palavras-chave são a class e a const.Você poderá adicionar tantas listas quanto desejar.

  Desde o &kde-frameworks; 5.53, uma lista pode incluir palavras-chave de outra lista ou linguagem/arquivo, usando o elemento `include`. O `##` é usado para separar o nome da lista e o nome da definição da linguagem, da mesma forma que na regra `IncludeRules`. 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 othername contém a palavra-chave str e todas as palavras-chave da lista types, que pertence à linguagem ISO C++.

  O elemento `contexts` contém todos os contextos. O primeiro contexto é, por padrão, o início do realce. Existem duas regras no contexto Normal Text (Texto Normal), que correspondem à lista de palavras-chave com o nome um_nome e uma regra que detecta aspas e muda o contexto para string (cadeia de caracteres). Para aprender mais sobre as regras, leia o próximo capítulo.

  A terceira parte é o elemento `itemDatas`. Contém todas as cores e estilos de fonte necessários pelos contextos e regras. Neste exemplo, são usados o `itemData` de Normal Text (Texto Normal), String (Cadeia de Caracteres) e Keyword (Palavra-Chave).

      <highlighting>
          <list name="somename">
            <item>class</item>
            <item>const</item>
          </list>
          <list name="othername">
            <item>str</item>
            <include>types##ISO C++</include>
          </list>
          <contexts>
            <context attribute="Normal Text" lineEndContext="#pop" name="Normal Text" >
              <keyword attribute="Keyword" context="#stay" String="somename" />
              <keyword attribute="Keyword" context="#stay" String="othername" />
              <DetectChar attribute="String" context="string" char="&quot;" />
            </context>
            <context attribute="String" lineEndContext="#stay" name="string" >
              <DetectChar attribute="String" context="#pop" char="&quot;" />
            </context>
          </contexts>
          <itemDatas>
            <itemData name="Normal Text" defStyleNum="dsNormal" />
            <itemData name="Keyword" defStyleNum="dsKeyword" />
            <itemData name="String" defStyleNum="dsString" />
          </itemDatas>
        </highlighting>

A última parte de uma definição de realce é a seção opcional `general`. 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.

- A seção `comment` define com que texto é introduzido um comentário para uma única linha. Você poderá também definir comentários multilinha, usando o multiLine com o atributo adicional end. Isto é usado se o usuário pressionar o atalho correspondente para comentar/descomentar.

  A seção `keywords` 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.

  As outras seções, `folding`, `emptyLines` e `spellchecking`, geralmente não são necessárias e serão explicadas posteriormente.

      <general>
          <comments>
            <comment name="singleLine" start="#"/>
            <comment name="multiLine" start="###" end="###" region="CommentFolding"/>
          </comments>
          <keywords casesensitive="1"/>
          <folding indentationsensitive="0"/>
          <emptyLines>
            <emptyLine regexpr="\s+"/>
            <emptyLine regexpr="\s*#.*"/>
          </emptyLines>
          <spellchecking>
            <encoding char="á" string="\'a"/>
            <encoding char="à" string="\`a"/>
          </spellchecking>
        </general>
      </language>

#### As Seções em detalhes

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.

O elemento `context` pertence ao grupo `contexts`. 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:

- O `name` declara o nome do contexto. As regras irão usar esse nome para indicar o contexto para onde mudar, se a regra corresponder.

  O `attribute` 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 attribute do contexto especificado no context da regra será usado.

  O `lineEndContext` 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 `#stay` para não mudar de contexto (⪚, não fazer nada) ou o `#pop` que fará com que saia deste contexto. É possível usar, por exemplo, `#pop#pop#pop` para sair de dentro de três contextos, ou ainda `#pop#pop!OutroContexto` para sair duas vezes e mudar para o contexto `OutroContexto`. Também é possível alternar para um contexto que pertence a outra definição de linguagem, da mesma forma que nas regras `IncludeRules`, por exemplo, `AlgumContexto##JavaScript`. As mudanças de contexto também são descritas em kate-highlight-rules-detailled. Padrão: #stay.

  O `lineEmptyContext` define o contexto, se for encontrada uma linha em branco. A nomenclatura das mudanças de contexto é a mesma que a descrita anteriormente em lineEndContext. Padrão: #stay.

  O `fallthroughContext` 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 lineEndContext. Padrão: #stay.

  O `fallthrough` define se o sistema de realce alterna para o contexto especificado em `fallthroughContext` caso nenhuma regra corresponda. Observe que, desde o &kde; &frameworks; 5.62, este atributo está obsoleto em favor de `fallthroughContext`, pois, se o atributo `fallthroughContext` estiver presente, subentende-se implicitamente que o valor de `fallthrough` é true. Padrão: false.

  O `noIndentationBasedFolding` 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 folding do grupo general. Padrão: false.

O elemento `itemData` está no grupo `itemDatas`. 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:

- O `name` define o nome do 'itemData'. Os contextos e regras irão usar este nome no seu atributo attribute, para referenciar um 'itemData'.

  O `defStyleNum` define qual o estilo padrão usar. Os estilos pré-definidos disponíveis são explicados mais tarde em detalhes.

  O `color` define uma cor. Os formatos válidos são o '#rrggbb' ou '#rgb'.

  O `selColor` define a cor da seleção.

  O `italic`, se for true (verdadeiro), irá colocar o texto em itálico.

  O `bold`, se for true (verdadeiro), irá colocar o texto em negrito.

  O `underline`, se for true (verdadeiro), irá colocar o texto sublinhado.

  O `strikeOut`, se for true (verdadeiro), o texto ficará traçado.

  O `spellChecking`, se for true (verdadeiro), será verificada a ortografia do texto.

O elemento `keywords`, no grupo `general`, define as propriedades das palavras-chave. Os atributos disponíveis são:

- O `casesensitive` poderá ser true (verdadeiro) ou false (falso). Se for true, todas as palavras-chave farão distinção entre maiúsculas e minúsculas.

  O `weakDeliminator` é uma lista de caracteres que não irão atuar como separadores de palavras. Por exemplo, o ponto `'.'` é um separador de palavras. Assuma que uma palavra-chave num `list` contém um ponto; nesse caso, só irá corresponder se indicar que o ponto é um delimitador fraco.

  O `additionalDeliminator` define os delimitadores ou separadores adicionais.

  O `wordWrapDeliminator` define os caracteres após os quais poderá ocorrer uma mudança de linha.

  Os delimitadores pré-definidos e de mudança de linha são os caracteres `.():!+,-<=>%&*/;?[]^{|}~\`, o espaço (`' '`) e a tabulação (`'\t'`).

O elemento `comment` no grupo `comments` define propriedades de comentário que são usadas para: Ferramentas Comentar, Ferramentas Descomentar e Ferramentas Alternar comentário. Os atributos disponíveis são:

- O `name` tanto poderá ser singleLine como multiLine. Se escolher o multiLine, serão necessários os atributos end e region. Se escolher singleLine, poderá adicionar o atributo opcional position.

  O `start` define o texto usado para iniciar um comentário. No C++, este será o "/*" em comentários de várias linhas. Este atributo é obrigatório para os tipos multiLine e singleLine.

  O `end` define o texto usado para fechar um comentário. No C++, será o "*/". Este atributo está disponível apenas e é obrigatório para comentários do tipo multiLine.

  O `region` deverá ser o nome do comentário multi-linhas que poderá expandir ou recolher. Assuma que tem o beginRegion="Comment" ... endRegion="Comment" nas suas regras; nesse caso, deverá usar o region="Comment". 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 multiLine.

  O `position` 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 position="afterwhitespace" 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 é afterwhitespace. Isso só está disponível para o tipo singleLine.

O elemento `folding`, no grupo `general`, define as propriedades de dobragem/desdobramento do código. Os atributos disponíveis são:

- O `indentationsensitive`, se for true, 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 é false.

O elemento `emptyLine` no grupo `emptyLines` define quais linhas devem ser tratadas como linhas vazias. Isso permite modificar o comportamento do atributo lineEmptyContext nos elementos `context`. Os atributos disponíveis são:

- O `regexpr` 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.

O elemento `encoding` no grupo `spellchecking` define uma codificação de caracteres para a verificação ortográfica. Atributos disponíveis:

- O `char` é um caractere codificado. Caso não seja especificada, a verificação ortográfica ignorará essa codificação.

  O `string` é uma sequência de caracteres que será codificada como o caractere char na verificação ortográfica. Por exemplo, na linguagem LaTeX, a string `\"{A}` representa o caractere `Ä`.

#### Estilos Padrão Disponíveis

Os estilos padrão já foram explicados, em resumo: Os estilos padrão são os estilos de cores e fontes pré-definidos.

Estilos padrão gerais:

- `dsNormal`, quando não é necessário nenhum realce em especial.

  `dsKeyword`, para as palavras-chave do idioma incorporadas.

  `dsFunction`, nas chamadas e definições de funções.

  `dsVariable`, se aplicável: nomes das variáveis (⪚ $algumaVariavel em PHP/Perl).

  `dsControlFlow`, palavras-chave de controle de fluxo, como o 'if', 'else', 'switch', 'break', 'return', 'yield', ...

  `dsOperator`, operadores como o + - * / :: < >

  `dsBuiltIn`, nas funções, classes e objetos incorporados.

  `dsExtension`, extensões comuns, como as classes e funções/macros do &Qt; em C++ e Python.

  `dsPreprocessor`, para as instruções do pré-processador ou para as definições de macros.

  `dsAttribute`, anotações como o @override e o __declspec(...).

Estilos padrão relacionados com as strings:

- `dsChar`, para caracteres únicos, como o 'x'.

  `dsSpecialChar`, caracteres com significados especiais nas strings, como as sequências de escape, substituições ou operadores de expressões regulares.

  `dsString`, para strings do tipo "olá mundo".

  `dsVerbatimString`, strings literais como o 'raw \backlash' do Perl, CoffeeScript e das linhas de comando, assim como o r'\raw' do Python.

  `dsSpecialString`, SQL, expressões regulares, documentação, modo matemático do &latex;, ...

  `dsImport`, importação, inclusão ou requisição de módulos.

Estilos padrão relacionados com números:

- `dsDataType`, para os tipos de dados incorporados, como o 'int', 'void', 'u64'.

  `dsDecVal`, nos valores decimais.

  `dsBaseN`, nos valores com uma base diferente de 10.

  `dsFloat`, nos valores de ponto flutuante.

  `dsConstant`, nas constantes incorporadas e definidas pelo usuário, como o PI.

Estilos padrão de comentários e relacionados com a documentação:

- `dsComment`, para comentários.

  `dsDocumentation`, para /** Comentários de documentação */ ou """strings de documentação""".

  `dsAnnotation`, para os comandos de documentação como o @param, @brief.

  `dsCommentVar`, os nomes das variáveis usadas nos comandos acima, como o "foobar" no @param foobar.

  `dsRegionMarker`, para marcadores de região, como o //BEGIN, //END nos comentários.

Outros estilos padrão:

- `dsInformation`, notas e dicas do tipo @note no doxygen.

  `dsWarning`, para os avisos do tipo @warning no doxygen.

  `dsAlert`, para palavras especiais como o TODO, FIXME, XXXX.

  `dsError`, para realçar erros e sintaxes inválidas.

  `dsOthers`, quando nada mais se aplica.

### Regras de Detecção de Realce

Esta seção descreve as regras de detecção de sintaxe.

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 atributo definido pela regra aos caracteres correspondentes; uma regra poderá perguntar se o contexto atual será alterado.

As regras se parecem com isto:

    <NomeRegra attribute="(identificador)" context="(identifier)" [atributos específicos da regra] />

O attribute identifica o estilo a usar para os caracteres correspondentes pelo nome ou índice; o context identifica, como esperado, o contexto a usar a partir daqui.

O context pode ser identificado por:

- Um identificador, que é o nome do outro contexto.

- Uma ordem diz ao mecanismo para ficar no contexto atual (`#stay`), ou voltar a usar um contexto usado anteriormente na string (`#pop`). Um contexto vazio ou ausente é equivalente a `#stay`.

  Para voltar mais passos, a palavra-chave #pop pode ser repetida: `#pop#pop#pop`

- Uma ordem seguida de um ponto de exclamação (!) e um identificador, que fará com que o mecanismo siga primeiro a ordem e depois mude para o outro contexto, ⪚ `#pop#pop!OtherContext`.

  Você pode empilhar vários contextos repetindo a marca (!) e um identificador`, por exemplo, `ContextA!ContextB!ContextC`. O último contexto da lista fica ativo imediatamente; os outros serão acessados ​​usando `#pop`.

- Um identificador, que é um nome de contexto, seguido por dois hashes (`##`) e outro identificador, que é o nome de uma definição de linguagem. Essa nomenclatura é similar à usada nas regras `IncludeRules` e permite que você alterne para um contexto pertencente a outra definição de realce de sintaxe, por exemplo, `AlgumContexto##JavaScript`.

Os atributos específicos da regra variam e estão descritos nas seções a seguir.

### Atributos comuns

Todas as regras possuem os seguintes atributos em comum e estão disponíveis sempre que os `(atributos comuns)` aparecerem. Todos os atributos são opcionais.

- attribute: Um atributo mapeia-se para um itemData definido. Padrão: attribute do contexto especificado no atributo context.

- context: Indica o contexto para onde muda o sistema de realce, se a regra corresponder. Padrão: #stay.

- beginRegion: Inicia um bloco de dobragem de código. Padrão: não definido.

- endRegion: Fecha uma região de dobragem de código. Padrão: não definido.

- lookAhead: Se for true (verdadeiro), o sistema de realce não irá processar o tamanho da correspondência. Padrão: false.

- firstNonSpace: Corresponder apenas se o texto for o primeiro não-espaço em branco da linha. Padrão: false.

- column: Corresponder apenas se a coluna corresponder. Padrão: não definido.

### Regras dinâmicas

Algumas regras permitem o atributo opcional `dynamic`, do tipo booleano, cujo valor padrão é false. Se o 'dynamic' for true, uma regra poderá usar sequências de substituição que representam o texto correspondente a uma expressão regular que mudou para o contexto atual, nos seus atributos `string` ou `char`. Num `string`, o texto de substituição `%N` (em que o N é um número) será substituído pela captura correspondente a `N` na expressão regular de chamada, iniciando de 1. Num `char`, a sequência de substituição deverá ser um número `N` que será substituído pelo primeiro caractere da captura `N` da expressão regular de chamada. Sempre que uma regra permitir este atributo, irá conter um (dinâmico).

- dynamic: poderá ser (true|false).

`Como isto funciona:`

Nas expressões regulares das regras `RegExpr`, todo o texto entre colchetes curvos simples `(PADRÃO)` é capturado e armazenado. Essas capturas podem ser usadas no contexto em que são alternadas, nas regras com o atributo `dynamic` true, por meio de `%N` (em String) ou `N` (em char).

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

- 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: `(?:PADRÃO)`

  Os grupos lookahead ou lookbehind, como `(?=PADRÃO)`, `(?!PADRÃO)` ou `(?<=PADRÃO)`, não são capturados. Consulte Expressões regulares para obter mais informações.

- Os grupos de captura podem ser usados ​​dentro da mesma expressão regular, usando `\N` em vez de `%N` respectivamente. Para mais informações, consulte Capturando texto correspondente (referências anteriores) em Expressões regulares.

Exemplo 1:

Neste exemplo simples, o texto correspondente à expressão regular `=*` é capturado e inserido em `%1` na regra dinâmica. Isso permite que o comentário termine com a mesma quantidade de `=` que no início. Isso corresponde a textos como: `[[ comentário ]]`, `[=[ comentário ]=]` ou `[=====[ comentário ]=====]`.

Além disso, as capturas estão disponíveis apenas no contexto alternado para Comentário de várias linhas.

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

Exemplo 2:

Na regra dinâmica, `%1` corresponde à captura que corresponde a `#+`, e `%2` a `&quot;+`. Isso corresponde ao texto como:`#label""""dentro do contexto""""#`.

Essas capturas não estarão disponíveis em outros contextos, como OtherContext, FindEscapes ou SomeContext.

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

Exemplo 3:

Isso corresponde a textos como: `Class::function<T>( ... )`.

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

### Delimitadores locais

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

- weakDeliminator: lista de caracteres que não atuam como delimitadores de palavras.

- additionalDeliminator: define os delimitadores ou separadores adicionais.

#### As regras em detalhes

DetectChar

- Detecta um caractere específico. Comumente usado, por exemplo, para encontrar o final das strings citadas.

      <DetectChar char="(caractere)" (atributos comuns) (dinâmico) />

  O atributo `char` define o caractere a ser procurado.

Detect2Chars

- Detecta dois caracteres específicos, em uma ordem definida.

      <Detect2Chars char="(caractere)" char1="(caractere)" (atributos comuns) />

  O atributo `char` define o primeiro caractere a ser procurado, e o atributo `char1` o segundo.

  Esta regra existe por razões históricas e, para facilitar a leitura, é preferível usar `StringDetect`.

AnyChar

- Detecta um caractere de um conjunto de caracteres especificados.

      <AnyChar String="(string)" (atributos comuns) />

  O atributo `String` define o conjunto de caracteres.

StringDetect

- Detecta uma string exata.

      <StringDetect String="(string)" [insensitive="true|false;"] (atributos comuns) (dinâmico) />

  O atributo `String` define a sequência a encontrar. O atributo `insensitive` é por padrão false e é passado à função de comparação de cadeias de caracteres. Se o valor for true a comparação não faz distinção entre maiúsculas e minúsculas.

WordDetect

- Detecta um texto exato, mas obriga adicionalmente a que esteja rodeado por limites de palavras, como um ponto `'.'` ou um espaço em branco no início e no fim da palavra. Pense em `\b<texto>\b` em termos de uma expressão regular, só que é mais rápido que a regra `Exp Reg`.

      <WordDetect String="(string)" [insensitive="true|false;"] (atributos comuns) (delimitadores locais) />

  O atributo `String` define a sequência a encontrar. O atributo `insensitive` é por padrão false e é passado à função de comparação de cadeias de caracteres. Se o valor for true a comparação não faz distinção entre maiúsculas e minúsculas.

  Desde: &kate; 3.5 (&kde; 4.5)

RegExpr

- Procura por uma expressão regular.

      <RegExpr String="(texto)" [insensitive="true|false"] [minimal="true|false"] (atributos comuns) (dinâmico) />

  O atributo `String` define a expressão regular.

  O `insensitive` é, por padrão, false e é passado ao motor de expressões regulares.

  O `minimal` é, por padrão, false e é passado ao motor de expressões regulares.

  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 (`^` ) indica que a regra deve ser coincidente somente no início da linha.

  Veja em Expressões Regulares mais informações sobre o assunto.

keyword

- Detecta uma palavra-chave de uma lista especificada.

      <keyword String="(nome da lista)" (atributos comuns) (delimitadores locais) />

  O atributo `String` identifica a lista de palavras-chave pelo nome. Uma lista com aquele nome, portanto, deve existir.

  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 additionalDeliminator da marca keywords.

  Se uma palavra-chave a corresponder conter um caractere separador, este caractere respectivo deverá ser adicionado à propriedade weakDeliminator da marca keywords. Este caractere irá então perder a sua propriedade de separador em todas as regras keyword. Também é possível usar o atributo weakDeliminator de keyword para que esta modificação se aplique apenas a esta regra.

Int

- Detecta um número inteiro (como a expressão regular: `\b[0-9]+`).

      <Int (atributos comuns) (delimitadores locais) />

  Esta regra não possui atributos específicos.

Float

- Detecta um número de ponto flutuante (como a expressão regular: `(\b[0-9]+\.[0-9]*|\.[0-9]+)([eE][-+]?[0-9]+)?`).

      <Float (atributos comuns) (delimitadores locais) />

  Esta regra não possui atributos específicos.

HlCOct

- Detecta uma representação de número de ponto octal (como a expressão regular: `\b0[0-7]+`).

      <HlCOct (atributos comuns) (delimitadores locais) />

  Esta regra não possui atributos específicos.

HlCHex

- Detecta uma representação numérica hexadecimal (como uma expressão regular: `\b0[xX][0-9a-fA-F]+`).

      <HlCHex (atributos comuns) (delimitadores locais) />

  Esta regra não possui atributos específicos.

HlCStringChar

- Detecta um caractere de escape.

      <HlCStringChar (atributos comuns) />

  Esta regra não possui atributos específicos.

  Corresponde a representações literais dos caracteres usados normalmente no código do programa como, por exemplo, o `\n` (nova linha) ou o `\t` (TAB).

  Os seguintes caracteres irão corresponder se estiverem após uma barra invertida (`\`): `abefnrtv"'?\`. Além disso, os números escapados em hexadecimal como, por exemplo, o `\xff` e os números octais escapados, como o `\033`, irão corresponder.

HlCChar

- Detecta um caractere do C.

      <HlCChar (atributos comuns) />

  Esta regra não possui atributos específicos.

  Corresponde aos caracteres em C colocados dentro de um tique (Exemplo: `'c'`). 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.

RangeDetect

- Detecta uma string com os caracteres de início e fim definidos.

      <RangeDetect char="(caractere)"  char1="(caractere)" (atributos comuns) />

  O `char` define o caractere de início e o `char1` o caractere que termina o intervalo.

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

LineContinue

- Corresponde um caractere específico indicado no fim de uma linha.

      <LineContinue (atributos comuns) [char="\"] />

  O atributo `char` define o caractere opcional a ser encontrado, sendo a barra invertida (`'\'`). o padrão. Novidade da versão 4.13 do &kde;.

  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.

IncludeRules

- Inclui as regras de outro contexto ou linguagem/arquivo.

      <IncludeRules context="ligacao_contexto" [includeAttrib="true|false"] />

  O atributo `context` define o contexto a incluir.

  Se for texto simples, inclui todas as regras definidas no contexto atual, como por exemplo:

      <IncludeRules context="outroContexto" />

  Se o texto conter um `##`, o sistema de realce irá procurar por um contexto de outra definição de linguagem com o nome indicado, por exemplo,

      <IncludeRules context="String##C++" />

  iria incluir o contexto String da definição de realce C++.

  Se o atributo `includeAttrib` for true, 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.

DetectSpaces

- Detecta espaços em branco.

      <DetectSpaces (atributos comuns) />

  Esta regra não possui atributos específicos.

  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.

DetectIdentifier

- Detecta os textos dos identificadores (como a expressão regular: `[a-zA-Z_][a-zA-Z0-9_]*`).

      <DetectIdentifier (atributos comuns) />

  Esta regra não possui atributos específicos.

  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.

#### Dicas & Truques

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.

- 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 `'#'` se for o primeiro caractere da linha. Uma solução baseada em expressões regulares seria semelhante à seguinte:

      <RegExpr attribute="Macro" context="macro" String="^\s*#" />

  Você poderá obter o mesmo se usar:

      <DetectChar attribute="Macro" context="macro" char="#" firstNonSpace="true" />

  Se quiser corresponder à expressão regular `'^#'`, poderá usar ainda o `DetectChar` com o atributo `column="0"`. O atributo `column` conta como caracteres; assim, uma tabulação conta como se fosse apenas um caractere.

- Nas regras `RegExpr`, use o atributo `column="0"` se o padrão `^PADRÃO` 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.

- Em expressões regulares, use grupos não capturantes `(?:PADRÃO)` em vez de grupos capturantes `(PADRÃO)`, 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.

- Você poderá mudar de contextos sem processar os caracteres. Assuma que deseja mudar de contexto quando encontrar o texto `*/`, mas necessita de processar essa sequência no próximo contexto. A regra abaixo irá corresponder e o atributo `lookAhead` fará com que o sistema de realce mantenha o texto correspondente no próximo contexto.

      <StringDetect attribute="Comment" context="#pop" String="*/" lookAhead="true" />

- Use o `DetectSpaces` se você souber que irão ocorrer vários espaços em branco.

- Use o `DetectIdentifier` em vez da expressão regular `'[a-zA-Z_]\w*'`.

- Use os estilos padrão sempre que puder. Desta forma, o usuário irá encontrar um ambiente familiar.

- Procure em outros arquivos &XML; para ver como as outras pessoas implementam as regras mais complicadas.

- Você pode validar todos os arquivos &XML; usando o comando `validatehl.sh mySyntax.xml`. O arquivo `validatehl.sh` usa `language.xsd` que estão disponíveis no Repositório de realce de sintaxe.

- Se repetir algumas expressões regulares complexas com frequência, você poderá usar as ENTIDADES. Por exemplo:

      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE language
      [
              <!ENTITY myref    "[A-Za-z_:][\w.:_-]*">
      ]>

  Agora, você poderá usar o &referencia; em vez da expressão regular.

- No editor do Kate, você pode recarregar as sintaxes usando a linha de comando integrada (atalho `F7` por padrão) e o comando `reload-highlighting`.

- Você pode usar o utilitário de linha de comando chamado `ksyntaxhighlighter6` (`kate-syntax-highlighter` em versões mais antigas) para testar uma sintaxe e exibir o estilo e as regiões associadas a cada parte de um texto.

  Resultado de `ksyntaxhighlighter6 --output-format=ansi --syntax-trace=format test.cpp`.

  Resultado de `ksyntaxhighlighter6 --output-format=ansi --syntax-trace=format test.cpp`.

  Use `ksyntaxhighlighter6 -h` para mais opções.

## Trabalhando com temas de cores

### Introdução

Os temas de cores definem as cores da área de edição de texto e do realce de sintaxe. Um tema de cores engloba o seguinte:

- O estilo do texto, usado para realce de sintaxe através dos atributos de estilo padrão. Por exemplo, a cor do texto e a cor do texto selecionada.

- O plano de fundo da área de edição de texto, incluindo a seleção de texto e a linha atual.

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

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

- Favoritos e trechos de código.

Para evitar confusão, o seguinte está fora do escopo:

- O tipo e o tamanho da fonte.

- 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 `esquema de cores global do &kde; &plasma;`, que é configurado no módulo Cores em &systemsettings; ou no próprio aplicativo, no menu Configurações Esquema de cores.

Temas de cores Breeze Light e Breeze Dark com realce de sintaxe para C++.

Temas de cores Breeze Light e Breeze Dark com realce de sintaxe para C++.

### O temas de cores do KSyntaxHighlighting

O framework KSyntaxHighlighting, que é o mecanismo de realce de sintaxe, é a biblioteca que `fornece e gerencia os temas de cores`. Isso faz parte do &kde; &frameworks; e é usado no editores de texto do &kde; como o &kate;, &kwrite;, &kile; e &kdevelop;. Essa dependência se parece com o seguinte:

Dependência das bibliotecas do &kde; &frameworks; 5 em editores de texto.

Dependência das bibliotecas do &kde; &frameworks; em editores de texto.

O KSyntaxHighlighting inclui uma variedade de temas integrados que são exibidos na página Temas de cores do site do editor Kate.

O framework KTextEditor, 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 Configurar do editor de texto. Mais detalhes em color-themes-gui.

A &GUI; para gerenciar temas de cores nas configurações do &kate;.

A &GUI; para gerenciar temas de cores nas configurações do &kate;.

É importante mencionar que, nos editores de texto do &kde;, como o &kate; ou o &kdevelop;, os temas de cores do KSyntaxHighlighting são usados ​​ desde o &kde; &frameworks; 5.75, 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 repositório do KSyntaxHighlighting inclui o script `utils/kateschema_to_theme_converter.py` e o utilitário `utils/schema-converter/` para essa finalidade.

### Formato &JSON; dos temas de cores

#### Introdução

Os temas de cores são armazenados em arquivos no formato &JSON;, com a extensão `.theme`.

No código-fonte do KSyntaxHighlighting, os arquivos &JSON; dos temas integrados estão localizados no diretório `data/themes/`. 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 exportando-os da &GUI; para gerenciar temas do KTextEditor.

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 `org.kde.syntax-highlighting/themes/` na sua pasta de usuário, que você pode encontrar com o comando ``qtpaths``--paths GenericDataLocation`` e geralmente são ``$HOME`/.local/share/` e `/usr/share/`.

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 é ``$HOME`/.var/app/`nome-pacote-flatpak`/data/org.kde.syntax-highlighting/themes/` e em um aplicativo Snap, esse local é ``$HOME`/snap/`nome-pacote-snap`/current/.local/share/org.kde.syntax-highlighting/themes/`.

No &Windows;, esses arquivos estão localizados em `%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\themes`. `%USERPROFILE%` geralmente se expande para `C:\Users\`nome-de-usuário``.

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

Para o usuário local | ``$HOME`/.local/share/org.kde.syntax-highlighting/themes/`
Para todos os usuários | `/usr/share/org.kde.syntax-highlighting/themes/`
Para pacotes Flatpak | ``$HOME`/.var/app/`nome-pacote-flatpak`/data/org.kde.syntax-highlighting/themes/`
Para pacotes Snap | ``$HOME`/snap/`nome-pacote-snap`/current/.local/share/org.kde.syntax-highlighting/themes/`
No &Windows; | `%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\themes`
No &macOS; | ``$HOME`/Library/Application Support/org.kde.syntax-highlighting/themes/`

Se existirem vários arquivos de tema com o mesmo nome, o arquivo com a `revision` mais alta será carregado.

#### A estrutura &JSON;

A estrutura de um arquivo &JSON; é explicada em seu site. Basicamente, um arquivo no formato JSON consiste em:

- Coleções de pares chave/valor, separados por vírgulas e agrupados em `{ }` que chamaremos de objetos.

- Listas ordenadas de valores, separados por vírgulas e agrupados em `[ ]` que chamaremos de array.

A nomenclatura chave, valor, objeto e array 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.

#### Seções principais dos arquivos de tema de cores &JSON;

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

- `metadata`: É obrigatória. O valor é um objeto com os metadados do tema, como nome, revisão e licença.

  Isto é detalhado em color-themes-json-metadata.

- `editor-colors`: É 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.

  Isto é detalhado em color-themes-editor-colors.

- `text-styles`: É obrigatória. O valor é um objeto com os atributos de estilo de texto padrão da sintaxe realce de sintaxe. Cada atributo define sua cor do texto, sua cor do texto selecionada ou se está em negrito ou itálico, por exemplo. Os estilos de texto podem ser referenciados a partir dos arquivos XML de definição de sintaxe.

  Isto é detalhado em color-themes-text-styles.

- `custom-styles`: É 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 `Python` ou `Markdown` você pode especificar um estilo de texto diferente que substitui o padrão definido em `text-styles`.

  Isto é detalhado em color-themes-custom-styles.

A linguagem &JSON; não suporta comentários. No entanto, você pode usar a chave opcional `_comments` 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.

Abaixo está um arquivo de exemplo para o tema Breeze Light. Você pode notar que, para evitar que o exemplo fique muito grande, os objetos `editor-colors` e `text-styles` não contêm todas as chaves necessárias. Você pode ver o arquivo completo do tema Breeze Light no repositório do KSyntaxHighlighting.

    {
        "_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 <vkrause@kde.org>",
                "SPDX-FileCopyrightText: 2016 Dominik Haumann <dhaumann@kde.org>"
            ],
            "license": "SPDX-License-Identifier: MIT"
        },
        "editor-colors": {
            "BackgroundColor" : "#ffffff",
            "CodeFolding" : "#94caef",
            "BracketMatching" : "#ffff00",
            "CurrentLine" : "#f8f7f6",
            "IconBorder" : "#f0f0f0",
            "IndentationLine" : "#d2d2d2",
            "LineNumbers" : "#a0a0a0",
            "CurrentLineNumber" : "#1e1e1e",
            As outras chaves de cor do editor...

        },
        "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"
            },
            As outras chaves de estilo de texto...

        },
        "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"
                }
            }
        }
    }

#### Metadados

O objeto &JSON; da chave `metadata` contém informações relevantes sobre o tema. Este objeto possui as seguintes chaves:

- `nome`: É uma string que define o nome da linguagem. Ela aparece nos menus e diálogos posteriormente. É obrigatória.

- `revision`: É um número inteiro 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.

- `license`: É uma string que define a licença do tema, usando o identificador `SPDX-License-Identifier` do formato de comunicação de licença padrão SPDX. É opcional.

  Você pode ver a lista completa de identificadores de licença SPDX aqui.

- `copyright`: É uma array de strings que especifica os autores do tema, usando o identificador `SPDX-FileCopyrightText` do formato de comunicação de licença padrão SPDX. É opcional.

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

### Cores em detalhes

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

#### Cores do editor

Corresponde às cores da área de edição de texto.

No arquivo de tema &JSON;, a chave respectiva `editor-colors` tem como valor um objeto onde cada chave referencia um atributo de cor do editor de texto. Aqui, `todas as chaves disponíveis são obrigatórias`, seus valores são `strings` com códigos de cores hexadecimais, como #00B5CF.

Na &GUI; para gerenciar temas do KTextEditor, esses atributos podem ser modificados na aba `Cores`.

As chaves disponíveis são as seguintes; as chaves usadas no arquivo &JSON; estão listadas em negrito, os nomes usados na &GUI; são mostrados entre parênteses.

Cores de fundo do editor

- `BackgroundColor` (Área do texto)

- Este é o plano de fundo padrão para a área do editor; será a cor dominante.

`TextSelection` (Texto selecionado)

- Este é o fundo para o texto selecionado.

`CurrentLine` (Linha atual)

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

`SearchHighlight` (Pesquisar realce)

- Define a cor do texto que corresponda à sua última pesquisa.

`ReplaceHighlight` (Substituir realce)

- Define a cor do texto que corresponda à sua última operação de substituição.

Borda do ícone

- `IconBorder` (Área de fundo)

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

`LineNumbers` (Números de linha)

- Esta cor é usada para desenhar os números de linha do lado esquerdo da janela, quando estiverem visíveis.

`CurrentLineNumber` (Número da linha atual)

- Esta cor é usada para desenhar o número da linha atual, no lado esquerdo da visualização. Definir isso um pouco diferente de LineNumbers ajuda a manter o foco na linha atual.

`Separator` (Separador)

- Esta cor é usada para desenhar a linha vertical que separa a borda do ícone do fundo da área de texto.

`WordWrapMarker` (Marcador de quebra de linha)

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

`CodeFolding` (Dobradura de código)

- 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 documentação de recolhimento de código.

`ModifiedLines` (Linhas modificadas)

- Esta cor é usada para destacar à esquerda de um documento as linhas que foram modificadas, mas ainda não salvas. Para mais informações, consulte kate-part-line-modification.

`SavedLines` (Linhas salvas)

- Esta cor é usada para destacar à esquerda de um documento as linhas que foram modificadas nesta sessão e salvas. Para mais informações, consulte kate-part-line-modification.

Decorações de texto

- `SpellChecking` (Linha com erro de ortografia)

- Esta cor é usada para indicar erros ortográficos.

`TabMarker` (Marcadores de espaço e tabulação)

- Esta cor é usada para desenhar os indicadores de espaços em branco, quando eles estiverem ativos.

`IndentationLine` (Recuo da linha)

- Esta cor é usada para desenhar uma linha à esquerda de blocos recuados, se esse recurso estiver ativado.

`BracketMatching` (Realce de parênteses)

- Esta cor é usada para desenhar o fundo dos parênteses correspondentes.

Cores dos marcadores

- `MarkBookmark` (Favorito)

- 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 kate-part-bookmarks.

`MarkBreakpointActive` (Ponto de parada ativo)

- 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 a documentação do plugin GDB.

`MarkBreakpointReached` (Ponto de parada atingido)

- 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 a documentação do plugin GDB.

`MarkBreakpointDisabled` (Ponto de parada desativado)

- 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 a documentação do plugin GDB.

`MarkExecution` (Execução)

- 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 a documentação do plugin GDB.

`MarkWarning` (Aviso)

- 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 a documentação do plugin de compilação.

`MarkError` (Erro)

- 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 a documentação do plugin de compilação.

Modelos de texto e trechos

- `TemplateBackground` (Fundo)

- Esta cor é usada pelo plugin de trechos do &kate; para marcar o fundo de um trecho de código. Para mais informações, consulte a documentação de trechos do &kate;.

`TemplatePlaceholder` (Espaço reservado editável)

- 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 a documentação de trechos do &kate;.

`TemplateFocusedPlaceholder` (Espaço reservado editável focado)

- 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 a documentação de trechos do &kate;.

`TemplateReadOnlyPlaceholder` (Espaço reservado não editável)

- 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 a documentação de trechos do &kate;.

#### Estilos de texto padrão

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.

Esses estilos de texto podem ser referenciados nos `estilos padrão` usados ​​nos arquivos de definição &XML; de realce de sintaxe. Por exemplo, o atributo Normal é equivalente a dsNormal nos arquivos &XML; e DataType é equivalente a dsDataType. Consulte kate-highlight-default-styles na documentação de realce de sintaxe.

Certifique-se de escolher cores legíveis com bom contraste, especialmente em combinação com as `Cores do editor`. Consulte color-themes-contrast.

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

    "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"
        },
        As outras chaves de estilo de texto...
    }

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

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

  `selected-text-color`: A cor do texto quando ele é selecionado geralmente tem o mesmo valor que text-color. Quando o texto é selecionado, o fundo é definido pelo valor de TextSelection em Cores do editor, portanto, você deve garantir que o texto tenha bom contraste e seja legível com esse fundo. O valor é uma string com um código de cor hexadecimal. Este par chave/valor é obrigatório.

  `bold`: É um booleano que determina se o texto está em negrito. Esta chave é opcional, o valor padrão é `false`.

  `italic`: É um booleano que determina se o texto está em itálico. Esta chave é opcional, o valor padrão é `false`.

  `underline`: É um booleano que determina se o texto está sublinhado. Esta chave é opcional, o valor padrão é `false`.

  `strike-through`: É um booleano que determina se o texto está riscado. Esta chave é opcional, o valor padrão é `false`.

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

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

Na &GUI; para gerenciar temas de cores do KTextEditor, esses atributos podem ser modificados na aba `Estilos de texto padrão`. 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.

As chaves de estilo de texto disponíveis são as seguintes; as chaves usadas no arquivo &JSON; estão listadas em negrito, os nomes usados na &GUI; são mostrados entre parênteses se forem diferentes.

Texto normal e código-fonte

- `Normal`: Estilo de texto padrão para texto normal e código-fonte sem realce especial.

  `Keyword`: Estilo de texto para palavras-chave de linguagem integradas.

  `Function`: Estilo de texto para definições de função e chamadas de função.

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

  `ControlFlow` (Fluxo de controle): Estilo de texto para palavras-chave de fluxo de controle, como if, then, else, return, switch, break, yield, continue, etc.

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

  `BuiltIn` (Integrado): Estilo de texto para classes de linguagem, funções e objetos integrados.

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

  `Preprocessor`: Estilo de texto para instruções do pré-processador ou definições de macro.

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

Números, tipos e constantes

- `DataType` (Tipo de dados): Estilo de texto para tipos de dados integrados como int, char, float, void, u64, etc.

  `DecVal` (Decimal/Valor): Estilo de texto para valores decimais.

  `BaseN` (Inteiro de base N): Estilo de texto para números com base diferente de 10.

  `Float` (Ponto flutuante): Estilo de texto para números de ponto flutuante.

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

Strings e caracteres

- `Char` (Caractere): Estilo de texto para caracteres únicos como `'x'`.

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

  `String`: Estilo de texto para strings como `olá mundo`.

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

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

  `Import` (Importações, Módulos, Inclusões): Estilo de texto para inclusões, importações, módulos ou pacotes &latex;.

Comentários e documentação

- `Comment`: Estilo de texto para comentários normais.

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

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

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

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

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

  `Warning`: Estilo de texto para avisos, como a palavra-chave `@warning` no Doxygen.

  `Alert`: Estilo de texto para palavras especiais em comentários, como `TODO`, `FIXME`, `XXXX` e `WARNING`.

Diversos

- `Error`: Estilo de texto indicando realce de erro e sintaxe incorreta.

  `Others`: Estilo de texto para atributos que não correspondem a nenhum dos outros estilos padrão.

#### Estilos de texto de realce personalizados

Aqui você pode definir estilos de texto para uma definição específica de realce de sintaxe, substituindo o `estilo de texto padrão` descrito na seção anterior.

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

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

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

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

- As definições de realce de sintaxe frequentemente incluem outras definições. Por exemplo, o realçador de sintaxe QML inclui o realçador de sintaxe JavaScript, já que compartilham funcionalidades de realce.

Na &GUI; para gerenciar temas do KTextEditor, esses atributos podem ser modificados na aba `Estilos de realce de texto`. 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 Alerta e muitos formatos de código-fonte importam o realce Doxygen.

### &GUI; dos temas de cores

A maneira mais simples de criar e editar temas de cores é através da &GUI; dentro da janela Configurar fornecida pelo KTextEditor. Para acessá-la, selecione Configurações Configurar `aplicativo`... na barra de menus do seu editor de texto. Isso abrirá a janela Configurar, onde você poderá selecionar Temas de cores no painel lateral.

Janela de configuração do &kate; com o gerenciamento de temas de cores.

Janela de configuração do &kate; com o gerenciamento de temas de cores.

Nesta janela 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 `.theme` com formato &JSON; ou importá-los de arquivos `.theme` externos. Cada tema possui configurações para cores e estilos de texto.

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

Você pode ajustar o esquema de cores global do &kde; no módulo Cores nas &systemsettings;. Você também pode alterá-lo individualmente em alguns aplicativos, como o &kate; ou o &kdevelop;, no menu Configurações Esquema de cores.

#### Criar um novo tema

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

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

#### Importar ou exportar arquivos de tema &JSON;

Você pode exportar um tema selecionado (incluindo os temas integrados) para um arquivo &JSON; com a extensão `.theme`, usando o botão Exportar. Isso abrirá uma janela para salvar o arquivo. Para adicionar um tema de cores de um arquivo &JSON; externo, basta pressionar o botão Importar e selecionar o arquivo `.theme` na janela.

- Como mencionado acima, os arquivos de tema personalizados pelo usuário são armazenados na pasta `org.kde.syntax-highlighting/themes/`. Ao copiar ou criar um tema, ele aparecerá automaticamente lá. Além disso, importar ou adicionar um tema é equivalente a copiar um arquivo `.theme` externo para esta pasta. O KSyntaxHighlighting detecta automaticamente os arquivos de tema de cores desta pasta.

- Se você deseja publicar um tema criado por você, é essencial verificar o objeto metadata do arquivo &JSON;, adicionando a licença respectiva e verificando o número da revisão.

#### Editando temas de cores

##### Cores

Aqui, as cores da área de edição de texto são ajustadas. Elas são detalhadas em color-themes-editor-colors.

##### Estilos de texto padrão

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.

O nome na lista de estilos está usando o estilo configurado para o item, oferecendo-lhe uma 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.

Os atributos desta área estão detalhados em color-themes-text-styles.

##### Estilos de texto de realce

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 Realce, acima da lista de estilos.

O nome na lista de estilos está usando o estilo configurado para o item, oferecendo-lhe uma visualização imediata ao configurar um estilo.

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.

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.

### Dicas & Truques

#### Contraste das cores do texto

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.

O aplicativo `Kontrast` é 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.

Você pode baixar o `Kontrast` do site de aplicativos do &kde; ou do pacote Flatpak no Flathub (somente para GNU/Linux).

O aplicativo `Contrast` do GNOME é semelhante. Você pode baixar o pacote Flatpak no Flathub (somente para GNU/Linux).

Um script Python no Repositório de realce de sintaxe permite visualizar todas as cores em um tema, bem como o contraste com os vários planos de fundo configurados.

#### Sugestões de consistência com o realce de sintaxe

O KSyntaxHighlighting inclui mais de 300 definições de realce de sintaxe, 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:

- Use negrito para os estilos de texto Keyword e ControlFlow.

- Não use cor de fundo em qualquer estilo de texto, exceto Alert e RegionMarker.

A maioria dos realçadores de sintaxe são projetados para ter uma boa aparência nos temas padrão Breeze Light e Breeze Dark, portanto, outra maneira de manter a consistência é usar cores semelhantes nos estilos de texto, como verde para Preprocessor e Others, azul para DataType e Attribute, ou roxo para Function.

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

## Scripts com &javascript;

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 plugin de trechos.

### Scripts de recuo

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.

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 `*.js`, chamado de, ⪚, `javascript.js` na pasta pessoal local `$`XDG_DATA_HOME`/katepart5/script/indentation`. Nesse sentido, a variável de ambiente `XDG_DATA_HOME` normalmente se expande para qualquer `~/.local` ou `~/.local/share`.

No &Windows; estes arquivos estão localizados em `%USERPROFILE%\AppData\Local\katepart5\script\indentation`. `%USERPROFILE%` que normalmente se expandem para `C:\\Users\\`usuário``.

#### O cabeçalho do script de recuo

O cabeçalho do arquivo `javascript.js` está incorporado como &JSON; no início do documento no seguinte formato:

    var katescript = {
        "name": "JavaScript",
        "author": "Nome de Exemplo <nome.exemplo@endereco.org>",
        "license": "BSD License",
        "revision": 1,
        "kate-version": "5.1",
        "required-syntax-style": "javascript",
        "indent-languages": ["javascript"],
        "priority": 0,
    }; // kate-script-header, deve estar no início do arquivo, sem comentários

Cada item será agora explicado em detalhes:

- `name` [obrigatório]: Este é o nome do modo de recuo que aparece no menu Ferramentas Recuar e na janela de configuração.

- `author` [opcional]: O nome e a informação de contato do autor.

- `license` [opcional]: Forma curta da licença, como por exemplo, BSD License ou LGPLv3.

- `revision` [obrigatório]: A versão do programa. Este número deverá ser aumentado sempre que o programa for modificado.

- `kate-version` [obrigatório]: A versão mínima do &kappname; necessária.

- `required-syntax-style` [opcional]: O estilo do sintaxe necessário, que corresponde ao `style` 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 comportamento inesperado causado pelo uso do recuador sem o esquema de realce esperado. Por exemplo, o recuado do Ruby faz uso dos arquivos `ruby.js` e `ruby.xml`.

- `indent-languages` [opcional]: Uma lista &JSON; de estilos de sintaxe que este módulo consegue recuar corretamente, ⪚: `["c++", "java"]`.

- `priority` [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.

#### O código-fonte do recuador

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:

    // Necessário para as bibliotecas js do katepart, ⪚ 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 FerramentasFormatar recuo
        // a variável 'caractere' está em branco, isto é, caractere == ''.
        //
        // ver também: API de Programação
        return -2;
    }

A função `indent()` tem três parâmetros:

- `linha`: a linha que tem de ser recuada

- `larguraRecuo`: o número de espaços correspondentes a cada recuo

- `caractere`: ou um caractere de mudança de linha (`ch == '\n'`), algum dos caracteres de ativação indicados em `caracteresAtivacao` ou vazio, caso o usuário tenha invocado a ação Ferramentas Alinhar.

O valor devolvido pela função `indent()` define como a linha será recuada. Se o valor devolvido for um número inteiro, é interpretado da seguinte forma:

- valor devolvido `-2`: não fazer nada

- valor devolvido `-1`: mantém o recuo (procura pela linha não-vazia anterior)

- valor devolvido `0`: números >= 0 definem a largura do recuo em espaços

Em alternativa, poderá ser devolvida uma lista com dois elementos:

- `return [ recuo, alinhamento ];`

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 alinhamento. 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 modo misto.

Considere o seguinte exemplo: Considerando que são usadas as tabulações para recuar, e que o tamanho da tabulação é de 4. Aqui, o <tab> representa uma tabulação e o '.' representa um espaço:

    1: <tab><tab>xpto("olá",
    2: <tab><tab>......."mundo");

Ao recuar a linha 2, a função `indent()` 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.

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 `$`XDG_DATA_DIRS`/katepart5/script/indentation`.

No &Windows; estes arquivos estão localizados em `%USERPROFILE%\AppData\Local\katepart5\script\indentation`. `%USERPROFILE%` que normalmente se expandem para `C:\\Users\\`usuário``.

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 `reload-scripts`.

Se você criar scripts úteis, considere a hipótese de contribuir com eles para o Projeto &kappname; enviando uma solicitação de mesclagem para nosso projeto no GitLab.

### Scripts de Linha de Comando

Uma funcionalidade semelhante a scripts de linha de comando também é fornecida no plugin de trechos. Este plugin pode fornecer um ponto de partida mais fácil, especialmente para pequenos scripts personalizados.

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 linha de comando incorporada. Por exemplo, o comando `sort` está implementado como um script. Esta seção explica como criar arquivos `*.js` que estendem o &kappname; com algumas funções auxiliares arbitrárias.

Os scripts de linha de comando estão localizados na mesma pasta que os scripts de recuo. Assim, como primeiro passo, crie um arquivo `*.js` novo, chamado `utilitários.js` na pasta pessoal local, em `$`XDG_DATA_HOME`/katepart5/script/commands`. Nesse sentido, a variável de ambiente `XDG_DATA_HOME` normalmente se expande para `~/.local` ou `~/.local/share`.

No Windows, esses arquivos estão localizados em `%USERPROFILE%\AppData\Local\katepart5\script\commands`. `%USERPROFILE%` geralmente se expande para `C:\\Users\\`usuário``.

#### O Cabeçalho do Script de Linha de Comando

O cabeçalho de cada script de linha de comando é está incorporado como &JSON; no início do script no seguinte formato:

    var katescript = {
        "author": "Nome de exemplo <nome.exemplo@endereco.org>",
        "license": "LGPLv2+",
        "revision": 1,
        "kate-version": "5.1",
        "functions": ["ordenar", "descerLinhas"],
        "actions": [
            {   "function": "ordenar",
                "name": "Ordena o texto selecionado",
                "category": "Edição",
                "interactive": "false"
            },
            {   "function": "descerLinhas",
                "name": "Desce as linhas",
                "category": "Edição",
                "shortcut": "Ctrl+Shift+Down",
                "interactive": "false"
            }
        ]
    }; // kate-script-header, deve estar no início do arquivo, sem comentários

Cada item será agora explicado em detalhes:

- `author` [opcional]: O nome e a informação de contato do autor.

- `license` [opcional]: Forma curta da licença, como por exemplo, BSD License ou LGPLv2.

- `revision` [obrigatório]: A versão do programa. Este número deverá ser aumentado sempre que o programa for modificado.

- `kate-version` [obrigatório]: A versão mínima do &kappname; necessária.

- `functions` [obrigatório]: Uma lista &JSON; dos comandos do script.

- `actions` [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 Associar combinações de teclas.

Uma vez que o valor de `functions` é 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 linha de comando incorporada do &kappname;.

#### O Código-Fonte do Programa

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 `ordenar` e `descerLinhas`. Todas as funções têm a seguinte sintaxe:

    // bibliotecas necessárias do katepart js, ⪚ range.js se você usar Range
    function <nome>(arg1, arg2, ...)
    {
        // ... implementação, ver também: API de Programação
    }

Os argumentos na linha de comando são passados à função como `arg1`, `arg2`, &etc; Para poder indicar a documentação de cada comando, basta implementar a função '`help`', como demonstrado a seguir:

    function help(cmd)
    {
        if (cmd == "sort") {
            return i18n("Ordena o texto selecionado.");
        } else if (cmd == "...") {
            // ...
        }
    }

Executar `help sort` na linha de comando, irá invocar esta função de ajuda com o argumento `cmd` igual ao comando indicado, como &ie;, `cmd == "sort"`. O &kappname; irá assim apresentar o texto devolvido como documentação ao usuário. Certifique-se de traduzir os textos.

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 `reload-scripts`.

##### Associar combinações de teclas

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 `ordenar` e `descerLinhas` aparecem no menu, graças ao seguinte componente no cabeçalho do script:

    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"
            }
        ]
    };

Os campos de uma ação são os seguintes:

- `function` [obrigatório]: A função que deverá aparecer no menu Ferramentas Scripts.

- `name` [obrigatório]: O texto que aparece no menu do script.

- `icon` [opcional]: O ícone aparece após ao texto no menu. Todos os nomes de ícones do &kde; poderão ser usados aqui.

- `category` [opcional]: Se for indicada uma categoria, o programa aparece num submenu.

- `shortcut` [opcional]: A combinação de teclas indicada aqui é o atalho de teclado padrão. Por exemplo: `Ctrl+Alt+T`. Veja a documentação do &Qt; para mais detalhes.

- `interactive` [opcional]: Se o script precisa de interação por parte do usuário na linha de comando, configure este valor como `true` (verdadeiro).

Se você criar scripts úteis, considere a hipótese de contribuir com eles para o Projeto &kappname; enviando uma solicitação de mesclagem para nosso projeto no GitLab.

### API de Programação

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 `Cursor` e o `Range` são fornecidas por arquivos de bibliotecas em `$`XDG_DATA_DIRS`/katepart5/libraries`. Elas serão necessárias, caso queira usar algumas das funções `Document` ou `View` no seu script. Inclua a biblioteca necessária usando:

    // bibliotecas necessárias do katepart js, ⪚ range.js se você usar Range
    require ("range.js");

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 `$`XDG_DATA_HOME`/katepart5/libraries` e incluí-lo no seu script usando:

    require ("myscriptnamehere.js");

No Windows, esses arquivos estão localizados em `%USERPROFILE%\AppData\Local\katepart5\libraries`. `%USERPROFILE%` geralmente se expande para `C:\\Users\\`usuário``.

Para estender os protótipos existentes, como o `Cursor` ou o `Range`, a forma recomendada é não modificar os arquivos `*.js` globais. Em vez disso, altere o protótipo do `cursor.js` em &javascript;, após o `cursor.js` que é incluído no seu script através do `require`.

#### Cursores e Intervalos

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 `(linha, coluna)` 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.

##### O Protótipo do Cursor

    Cursor();

- Construtor. Devolve um Cursor na posição `(0, 0)`.

  Exemplo: `var cursor = new Cursor();`

    Cursor(int linha, int coluna);

- Construtor. Devolve um Cursor na posição (linha, coluna).

  Exemplo: `var cursor = new Cursor(3, 42);`

    Cursor(Cursor outro);

- Construtor de cópia. Devolve uma cópia do cursor `outro`.

  Exemplo: `var copia = new Cursor(outro);`

    Cursor Cursor.clone();

- Devolve uma cópia do cursor.

  Exemplo: `var clone = cursor.clone();`

    Cursor.setPosition(int linha, int coluna);

- Configura a posição do cursor em `linha` e `coluna`.

  Desde: &kde; 4.11

    bool Cursor.isValid();

- Verifica se o cursor é válido. O cursor é inválido no caso em que a linha e/ou coluna sejam iguais a `-1`.

  Exemplo: `var valido = cursor.isValid();`

    Cursor Cursor.invalid();

- Devolve um novo cursor inválido, localizado em `(-1, -1)`.

  Exemplo: `var cursorInvalido = cursor.invalid();`

    int Cursor.compareTo(Cursor outro);

- Compara este cursor com o cursor `outro`. Devolve

  - `-1`, se este cursor for localizado antes do cursor `outro`,

  - `0`, se ambos os cursores forem iguais e

  - `+1`, se este cursor se localizar após o cursor `outro`.

    bool Cursor.equals(Cursor outro);

- Devolve `true` (verdadeiro), se este o cursor e o `outro` forem iguais, caso contrário devolve `false` (falso).

    String Cursor.toString();

- Devolve o cursor como um texto no formato `Cursor(linha, coluna)`.

##### O Protótipo do Intervalo

    Range();

- Construtor. A invocação de `new Range()` devolve um intervalo Range de (0, 0) - (0, 0).

    Range(Cursor inicio, Cursor fim);

- Construtor. A invocação de `new Range(`início`, `fim`)` devolve o intervalo (`início`, `fim`).

    Range(int linhaInicial, int colunaInicial, int linhaFinal, int colunaFinal);

- Construtor. A invocação de `new Range(`linhaInicial`, `colunaInicial`, `linhaFinal`, `colunaFinal`)` devolve um intervalo Range de (`linhaInicial`, `colunaInicial`) até (`linhaFinal`, `colunaFinal`).

    Range(Range outro);

- Construtor de cópia. Devolve uma cópia do intervalo Range `outro`.

    Range Range.clone();

- Devolve uma cópia do intervalo.

  Exemplo: `var clone = intervalo.clone();`

    bool Range.isEmpty();

- Devolve `true` (verdadeiro), se o cursor de início e de fim forem iguais.

  Exemplo: `var vazio = intervalo.isEmpty();`

  Desde: &kde; 4.11

    bool Range.isValid();

- Devolve `true` (verdadeiro), se tanto o cursor de início como o de fim forem válidos, caso contrário devolve `false` (falso).

  Exemplo: `var valido = intervalo.isValid();`

    Range Range.invalid();

- Devolve o intervalo Range de (-1, -1) até (-1, -1).

    bool Range.contains(Cursor cursor);

- Devolve `true` (verdadeiro) se este intervalo contiver a posição do cursor, caso contrário, devolve `false` (falso).

    bool Range.contains(Range outro);

- Devolve `true` (verdadeiro) se este intervalo contiver o intervalo Range `outro`, caso contrário, devolve `false` (falso).

    bool Range.containsColumn(int coluna);

- Devolve `true` (verdadeiro) se a `coluna` estiver no intervalo semiaberto `[início.coluna, fim.coluna)`, caso contrário, devolve `false` (falso).

    bool Range.containsLine(int linha);

- Devolve `true` (verdadeiro) se a `linha` estiver no intervalo semiaberto `[início.linha, fim.linha)`, caso contrário, devolve `false` (falso).

    bool Range.overlaps(Range outro);

- Devolve `true` (verdadeiro) se este intervalo e o intervalo `outro` compartilharem uma região em comum, caso contrário devolve `false` (falso).

    bool Range.overlapsLine(int linha);

- Devolve `true` (verdadeiro) se a `linha` estiver no intervalo `[início.linha, fim.linha]`, caso contrário devolve `false` (falso).

    bool Range.overlapsColumn(int coluna);

- Devolve `true` (verdadeiro) se a `coluna` estiver no intervalo `[início.coluna, fim.coluna]`, caso contrário devolve `false` (falso).

    bool Range.onSingleLine();

- Devolve `true` (verdadeiro) se o intervalo inicia e termina na mesma linha, &ie;, se `Range.start.line == Range.end.line`.

  Desde: &kde; 4.9

    bool Range.equals(Range outro);

- Devolve `true` (verdadeiro) se este intervalo e o intervalo `outro` forem iguais, caso contrário devolve `false` (falso).

    String Range.toString();

- Devolve o intervalo como uma string no formato `Range(Cursor(linha, coluna), Cursor(linha, coluna))`.

#### Funções globais

Esta seção apresenta todas as funções globais.

##### Arquivos de leitura e inclusão

    String read(String arquivo);

- Irá procurar pelo `arquivo` indicado em relação à pasta `katepart5/script/files` e irá devolver o seu conteúdo como texto.

    void require(String Arquivo);

- Irá procurar pelo `arquivo` indicado em relação à pasta `katepart5/script/libraries` e avaliá-lo. O `require` está protegido internamente contra inclusões múltiplas do mesmo `arquivos`.

  Desde: &kde; 4.10

##### Depuração

    void debug(String texto);

- Imprime o `texto` no `stdout`, mais precisamente no console que lança a aplicação.

##### Tradução

Para um suporte regional completo, existem diversas funções para traduzir os textos nos programas, nomeadamente o `i18n`, o `i18nc`, o `i18np` e o `i18ncp`. Estas funções comportam-se exatamente como as funções de tradução do &kde;.

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.

    void i18n(String texto, arg1, ...);

- Traduz o `texto` na língua usada pela aplicação. Os argumentos `arg1`, ..., são opcionais e usados para substituir os itens `%1`, `%2`, &etc;

    void i18nc(String contexto, String texto, arg1, ...);

- Traduz o `texto` na língua usada pela aplicação. Além disso, o texto do `contexto` fica visível aos tradutores para que possam dar uma tradução mais adequada. Os argumentos `arg1`, ..., são opcionais e são usados para substituir os itens de substituição `%1`, `%2`, &etc;

    void i18np(String singular, String plural, int número, arg1, ...);

- Traduz tanto o texto `singular` como o `plural` para a língua usada pela aplicação, dependendo do `número` indicado. Os argumentos `arg1`, ..., são opcionais e usados para substituir os itens de substituição `%1`, `%2`, &etc;

    void i18ncp(String contexto, String singular, String plural, intnúmero, arg1, ...);

- Traduz tanto o texto `singular` como o `plural` para a língua usada pela aplicação, dependendo do `número` indicado. Adicionalmente, o texto do `contexto` é visível para as tradutores, para que possam fornecer uma tradução mais adequada. Os argumentos `arg1`, ..., são opcionais e são usados para substituir os itens `%1`, `%2`, &etc;

#### A API do View

Sempre que um programa está sendo executado, existe uma variável global `view` que representa a área de edição ativa no momento. Segue-se uma lista com todas as funções disponíveis para o View.

    void view.copy()

- Copia a seleção se houver uma, caso contrário, a linha atual se a opção `[ ] Copiar/Recortar a linha atual se nenhuma seleção` estiver definida.

  Desde: &kde-frameworks; 5.79

    void view.cut()

- Recorta a seleção se houver uma, caso contrário, a linha atual se a opção `[ ] Copiar/Recortar a linha atual se nenhuma seleção` estiver definida.

  Desde: &kde-frameworks; 5.79

    void view.paste()

- Cola o conteúdo da área de transferência.

  Desde: &kde-frameworks; 5.79

    Cursor view.cursorPosition()

- Devolve a posição atual do cursor na janela.

    void view.setCursorPosition(int linha, int coluna);
    void view.setCursorPosition(Cursor cursor);

- Altera a posição atual do cursor para uma (linha, coluna) qualquer ou para o cursor indicado.

    Cursor view.virtualCursorPosition();

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

    void view.setVirtualCursorPosition(int linha, int coluna);
    void view.setVirtualCursorPosition(Cursor cursor);

- Altera a posição atual do cursor virtual para uma (linha, coluna) qualquer ou para o cursor indicado.

    String view.selectedText();

- Devolve o texto selecionado. Se não tiver nenhum texto selecionado, o texto devolvido vem vazio.

    bool view.hasSelection();

- Devolve `true` (verdadeiro) se a janela contiver algum texto selecionado, caso contrário, devolve `false` (falso).

    Range view.selection();

- Devolve o intervalo de texto selecionado. O intervalo devolvido é inválido, caso não esteja selecionado nenhum texto.

    void view.setSelection(Range intervalo);

- Altera o texto selecionado para o intervalo indicado.

    void view.removeSelectedText();

- Remove o texto selecionado. Se a janela não tiver nenhuma seleção feita, isto não faz nada.

    void view.selectAll();

- Seleciona todo o texto no documento.

    void view.clearSelection();

- Limpa a seleção de texto atual, sem remover o texto.

    void view.setBlockSelection(bool on);

- Liga/desliga o modo de seleção de blocos.

    bool view.blockSelection();

- Devolve `true` (verdadeiro) se o modo de seleção de bloco estiver ligado, caso contrário, devolve `false` (falso).

    void view.align(Range intervalo);

- Ajusta corretamente o recuo das linhas dentro do `intervalo` de acordo com as configurações de recuo atuais.

    void view.alignOn(Range intervalo, String padrão = "");

- Alinha as linhas no `intervalo` na coluna especificada pela expressão regula `padrão`. Com um `padrão` 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.

  Exemplos:

  `view.alignOn(document.documentRange(), '-');` irá inserir espaços antes do primeiro `-` de cada linha para alinhá-las todas na mesma coluna.

  `view.alignOn(document.documentRange(), ':\\s+(.)');` 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.

    object view.executeCommand(String comando,
                               String args,
                               Range intervalo);

- Executa o comando de linha de comando `comando` com os argumentos opcionais `args` e o intervalo opcional `intervalo`. O objeto retornado `object` possui uma propriedade booleana `object.ok` que indica se a execução do comando `comando` foi bem-sucedida. Em caso de erro, a string `object.status` contém uma mensagem de erro.

  Desde: &kde-frameworks; 5.50

    Range view.searchText(Range intervalo,
                          String padrão,
                          bool backwards = false);

- Busca a primeira ocorrência do `padrão` em `intervalo` e retorna o intervalo correspondente. A busca é realizada de trás para frente se o parâmetro booleano opcional `backwards` estiver definido como `true`.

  O intervalo retornado é inválido (consulte Range.isValid()) se `padrão` não for encontrado no `intervalo`.

  Desde: &kde-frameworks; 5.97

#### API do Document

Sempre que um script estiver em execução, existe um objeto global (variável) `document` representando o documento ativo atual. A seguir é apresentada uma lista de todas as funções disponíveis para o Document.

    String document.fileName();

- Devolve o nome do arquivo do documento, ou então um texto vazio para as janelas de texto ainda por salvar.

    String document.url();

- Devolve o &URL; completo do documento, ou então um texto vazio para as janelas de texto ainda por salvar.

    String document.mimeType();

- Devolve o tipo &MIME; do documento, ou então o tipo &MIME; `application/octet-stream` se não for encontrado qualquer tipo &MIME; apropriado.

    String document.encoding();

- Devolve a codificação usada atualmente para salvar o arquivo.

    String document.highlightingMode();

- Devolve o modo de realce global usado para todo o documento.

    String document.highlightingModeAt(Cursor pos);

- Devolve o modo de realce usado na posição do cursor indicada do documento.

    Array document.embeddedHighlightingModes();

- Devolve uma lista com os modos de realce incorporados neste documento.

    bool document.isModified();

- Devolve `true` (verdadeiro) se o documento tiver alguma alteração por salvar, caso contrário devolve `false`.

    String document.text();

- 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 `\n`.

    String document.text(int daLinha, int daColuna, int paraLinha, int paraColuna);
    String document.text(Cursor de, Cursor para);
    String document.text(Range intervalo);

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

    String document.line(int linha);

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

    String document.wordAt(int linha, int coluna);
    String document.wordAt(Cursor cursor);

- Devolve a palavra na posição do cursor indicada.

    Range document.wordRangeAt(int linha, int coluna);
    Range document.wordRangeAt(Cursor cursor);

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

  Desde: &kde; 4.9

    String document.charAt(int linha, int coluna);
    String document.charAt(Cursor cursor);

- Devolve o caractere na posição do cursor indicada.

    String document.firstChar(int linha);

- Devolve o primeiro caractere na `linha` 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.

    String document.lastChar(int linha);

- Devolve o último caractere da `linha` 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.

    bool document.isSpace(int linha, int coluna);
    bool document.isSpace(Cursor cursor);

- Devolve `true` (verdadeiro), se o caractere na posição indicada do cursor for um espaço em branco, caso contrário, devolve `false` (falso).

    bool document.matchesAt(int linha, int coluna, String texto);
    bool document.matchesAt(Cursor cursor, String texto);

- Devolve `true` (verdadeiro) se o `texto` indicado corresponder à posição indicada do cursor, caso contrário, devolve `false` (falso).

    bool document.startsWith(int linha, String texto, bool ignorarEspacos);

- Devolve `true` (verdadeiro) se a linha começar por `texto`, caso contrário, devolve `false` (falso). O argumento `ignorarEspacos` controla se os espaços envolventes são ignorados ou não.

    bool document.endsWith(int linha, String texto, bool ignorarEspacos);

- Devolve `true` (verdadeiro), caso a linha termine em `texto`, caso contrário devolve `false` (falso). O argumento `ignorarEspacos` controla se os espaços envolventes são ignorados.

    bool document.setText(String texto);

- Altera o texto do documento por inteiro.

    bool document.clear();

- Limpa o texto no documento por inteiro.

    bool document.truncate(int linha, int coluna);
    bool document.truncate(Cursor cursor);

- Trunca a linha indicada, na coluna ou posição do cursor indicadas. Devolve `true` (verdadeiro) em caso de sucesso ou `false` (falso) se a linha não estiver dentro do intervalo do documento.

    bool document.insertText(int linha, int coluna, String texto);
    bool document.insertText(Cursor cursor, String texto);

- Insere o `texto` na posição do cursor indicada. Devolve `true`, em caso de sucesso, ou `false` (falso), se o documento estiver apenas para leitura.

    bool document.removeText(int daLinha, int daColuna, int paraLinha, int paraColuna);
    bool document.removeText(Cursor de, Cursor para);
    bool document.removeText(Range intervalo);

- Remove o texto no intervalo indicado. Devolve `true` (verdadeiro), em caso de sucesso, ou `false` (falso), se o documento estiver no modo apenas para leitura.

    bool document.insertLine(int linha, String texto);

- Insere o texto na linha indicada. Devolve `true` (verdadeiro), em caso de sucesso, ou `false` (falso), caso o documento esteja apenas para leitura ou se a linha não estiver no intervalo do documento.

    bool document.removeLine(int linha);

- Remove a linha de texto indicada. Devolve `true` (verdadeiro), em caso de sucesso, ou `false` (falso), caso o documento esteja no modo apenas para leitura ou se a linha não estiver no intervalo do documento.

    bool document.wrapLine(int linha, int coluna);
    bool document.wrapLine(Cursor cursor);

- Reparte a linha na posição indicada pelo cursor. Devolve `true` (verdadeiro) em caso de sucesso ou `false` (falso) se, ⪚, a linha < 0.

  Desde: &kde; 4.9

    void document.joinLines(int linhaInicial, int linhaFinal);

- Junta as linhas de `linhaInicial` até `linhaFinal`. Duas linhas de texto sucessivas estão sempre separadas por um espaço em branco.

    int document.lines();

- Devolve o número de linhas do documento.

    bool document.isLineModified(int linha);

- Devolve `true` (verdadeiro), se a `linha` contém dados que não foram salvos.

  Desde: &kde; 5.0

    bool document.isLineSaved(int linha);

- Devolve `true` (verdadeiro), se a `linha` foi alterada, mas o documento foi salvo. Assim, a linha não contém dados não salvos.

  Desde: &kde; 5.0

    bool document.isLineTouched(int linha);

- Devolve `true` (verdadeiro), se a `linha` contém dados que não foram salvos ou foi anteriormente alterado.

  Desde: &kde; 5.0

    bool document.findTouchedLine(int linhaInicial, bool abaixo);

- Procura pela próxima linha tocada que comece na `linha`. A pesquisa é efetuada tanto para cima como para baixo, dependendo da direção de pesquisa indicada em `baixo`.

  Desde: &kde; 5.0

    int document.length();

- Devolve o número de caracteres do documento.

    int document.lineLength(int linha);

- Devolve o comprimento da `linha`.

    void document.editBegin();

- Inicia um grupo de edição para agrupar operações a desfazer/refazer. Certifique-se de invocar sempre o `editEnd()` tantas vezes quanto invoca o `editBegin()`. A invocação do `editBegin()` usa um contador de referências interno, &ie;, esta chamada pode ser encadeada.

    void document.editEnd();

- Termina um grupo de edição. A última invocação do `editEnd()` (&ie;, a correspondente à primeira chamada do `editBegin()`) termina o passo de edição.

    int document.firstColumn(int linha);

- Devolve a primeira coluna não em branco para a `linha` indicada. Se só existirem espaços em branco na linha, o valor devolvido é `-1`.

    int document.lastColumn(int linha);

- Devolve a última coluna que não esteja em branco para a `linha` indicada. Se só existirem espaços em branco na linha, o valor devolvido é `-1`.

    int document.prevNonSpaceColumn(int linha, int coluna);
    int document.prevNonSpaceColumn(Cursor cursor);

- Devolve a coluna com caracteres não-brancos que começa na posição de cursor indicada e pesquisa para trás.

    int document.nextNonSpaceColumn(int linha, int coluna);
    int document.nextNonSpaceColumn(Cursor cursor);

- Devolve a coluna com caracteres não-brancos que começa na posição de cursor indicada e pesquisa para a frente.

    int document.prevNonEmptyLine(int linha);

- Devolve a primeira linha não-vazia que contém caracteres não-nulos, pesquisando depois para trás.

    int document.nextNonEmptyLine(int linha);

- Devolve a primeira linha não-vazia que contém caracteres não-nulos, pesquisando depois para a frente.

    bool document.isInWord(String caractere, int atributo);

- Devolve `true` (verdadeiro), caso o `caractere` e `atributo` indicados possam fazer parte de uma palavra, caso contrário devolve `false` (falso).

    bool document.canBreakAt(String caractere, int atributo);

- Devolve `true` (verdadeiro) se o `caractere` indicado com o `atributo` indicado for adequado para mudar de linha, caso contrário devolve `false`.

    bool document.canComment(int atributoInicial, int atributoFinal);

- Devolve `true` (falso), caso um intervalo que começa e termina com os atributos indicados possa ser comentado; caso contrário, devolve `false` (falso).

    String document.commentMarker(int atributo);

- Devolve o marcador de comentários, usado em linhas únicas, para um determinado `atributo`.

    String document.commentStart(int atributo);

- Devolve o marcador de início de comentários, usado em linhas múltiplas, para um determinado `atributo`.

    String document.commentEnd(int atributo);

- Devolve o marcador de fim de comentários, usado em linhas múltiplas, para um determinado `atributo`.

    Range document.documentRange();

- Devolve um intervalo que engloba todo o documento.

    Cursor documentEnd();

- Devolve um cursor posicionado na última coluna da última linha do documento.

    bool isValidTextPosition(int linha, int coluna);
    bool isValidTextPosition(Cursor cursor);

- Devolve `true` (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.

  Desde: &kde; 5.0

    int document.attribute(int linha, int coluna);
    int document.attribute(Cursor cursor);

- Devolve o atributo na posição do cursor indicada.

    bool document.isAttribute(int linha, int coluna, int atributo);
    bool document.isAttribute(Cursor cursor, int atributo);

- Devolve `true` (verdadeiro), se o atributo na posição do cursor indicada for igual a `atributo`, caso contrário devolve `false` (falso).

    String document.attributeName(int linha, int coluna);
    String document.attributeName(Cursor cursor);

- Devolve o nome do atributo como um texto legível. Isto é igual ao nome `itemData` dos arquivos de realce de sintaxe.

    bool document.isAttributeName(int linha, int coluna, String nome);
    bool document.isAttributeName(Cursor cursor, String nome);

- Devolve `true` (verdadeiro), se o nome do atributo, numa dada posição do cursor, corresponder ao `nome` indicado, caso contrário devolve `false` (falso).

    String document.variable(String chave);

- Devolve o valor da variável do documento identificada pela `chave`. Se a variável do documento não existir, o valor devolvido é um texto em branco.

    void document.setVariable(String chave, String valor);

- Define o valor da variável do documento solicitada pela `chave`.

  Veja também: Variáveis de documento do Kate

  Desde: &kde; 4.8

    int document.firstVirtualColumn(int linha);

- Devolve a coluna virtual do primeiro caractere não-nulo na linha indicada, ou então `-1` se a linha estiver em branco ou só tiver caracteres de espaços em branco.

    int document.lastVirtualColumn(int linha);

- Devolve a coluna virtual do último caractere não-nulo na linha indicada, ou então `-1` se a linha estiver em branco ou só tiver caracteres de espaços em branco.

    int document.toVirtualColumn(int linha, int coluna);
    int document.toVirtualColumn(Cursor cursor);
    Cursor document.toVirtualCursor(Cursor cursor);

- Converte a posição do cursor real para uma posição virtual, retornando um int ou um objeto Cursor.

    int document.fromVirtualColumn(int linha, int colunaVirtual);
    int document.fromVirtualColumn(Cursor cursorVirtual);
    Cursor document.fromVirtualCursor(Cursor cursorVirtual);

- Converte a posição virtual do cursor para uma posição do cursor real, retornando um int ou um objeto Cursor.

    Cursor document.anchor(int linha, int coluna, Char caractere);
    Cursor document.anchor(Cursor cursor, Char caractere);

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

    Cursor document.rfind(int linha, int coluna, String texto, int atributo = -1);
    Cursor document.rfind(Cursor cursor, String texto, int atributo = -1);

- Pesquisa para trás pelo texto indicado, com o `atributo` apropriado. O argumento `atributo` é ignorado se for igual a `-1`. O cursor devolvido é inválido, caso o texto não tenha sido encontrado.

    int document.defStyleNum(int linha, int coluna);
    int document.defStyleNum(Cursor cursor);

- Devolve o estilo padrão que é usado na posição do cursor indicada.

    bool document.isCode(int linha, int coluna);
    bool document.isCode(Cursor cursor);

- Devolve `true` (verdadeiro) se o atributo na posição do cursor indicada não for igual a todos os seguintes estilos: `dsComment`, `dsString`, `dsRegionMarker`, `dsChar`, `dsOthers`.

    bool document.isComment(int linha, int coluna);
    bool document.isComment(Cursor cursor);

- Devolve `true` se o atributo do caractere na posição do cursor for `dsComment`, caso contrário, devolve `false`.

    bool document.isString(int linha, int coluna);
    bool document.isString(Cursor cursor);

- Devolve `true` (verdadeiro) se o atributo do caractere na posição do cursor for `dsString`, caso contrário, devolve `false` (falso).

    bool document.isRegionMarker(int linha, int coluna);
    bool document.isRegionMarker(Cursor cursor);

- Devolve `true` (verdadeiro) se o atributo do caractere na posição do cursor for `dsRegionMarker`, caso contrário, devolve `false` (falso).

    bool document.isChar(int linha, int coluna);
    bool document.isChar(Cursor cursor);

- Devolve `true` (verdadeiro) se o atributo do caractere na posição do cursor for `dsChar`, caso contrário, devolve `false` (falso).

    bool document.isOthers(int linha, int coluna);
    bool document.isOthers(Cursor cursor);

- Devolve `true` (verdadeiro) se o atributo do caractere na posição do cursor for `dsOthers`, caso contrário, devolve `false` (falso).

    void document.indent(Range intervalo, int número);

- Recua todas as linhas em `intervalo` por `número` de tabulações ou `número` vezes `tabSize` espaços, dependendo das preferências do usuário. O parâmetro `número` pode ser negativo.

#### A API do editor

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.

    String editor.clipboardText();

- Retorna o texto que está atualmente na área de transferência global.

  Desde: &kde-frameworks; 5.50

    String editor.clipboardHistory();

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

  Desde: &kde-frameworks; 5.50

    void editor.setClipboardText(String texto);

- Define o conteúdo da área de transferência para `texto`. O `texto` será adicionado ao histórico da área de transferência.

  Desde: &kde-frameworks; 5.50