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:

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

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

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.

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

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

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

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

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.

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.

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

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.

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

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

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.

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.

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.

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:

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.