Els temes de color s'emmagatzemen en fitxers de format JSON, amb l'extensió .theme.

En el codi font de KSyntaxHighlighting, els fitxers JSON dels temes integrats es troben a la carpeta data/themes/. Cal tenir en compte que en els editors de text, els temes integrats es compilen a dins de la biblioteca KSyntaxHighlighting, per tant, la forma d'accedir-hi és a través del codi font o exportant-la des de la IGU per a gestionar els temes de KTextEditor.

També és possible afegir amb facilitat temes addicionals o personalitzats, els quals es carreguen des del sistema de fitxers. Els fitxers de tema personalitzats per l'usuari es troben a la carpeta org.kde.syntax-highlighting/themes/ en la vostra carpeta d'usuari, la qual trobareu amb l'ordre qtpaths --paths GenericDataLocation que normalment és $HOME/.local/share/ i /usr/share/.

En els paquets Flatpak i Snap, la carpeta anterior no funcionarà, ja que la ubicació de les dades és diferent per a cada aplicació. En una aplicació de Flatpak, aquesta ubicació generalment és $HOME/.var/app/nom_paquet_flatpak/data/org.kde.syntax-highlighting/themes/ i en una aplicació de Snap aquesta ubicació és $HOME/snap/nom_paquet_snap/current/.local/share/org.kde.syntax-highlighting/themes/.

Al Windows® aquests fitxers es troben a %USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\themes. %USERPROFILE% que generalment s'expandeix a C:\Users\nom_usuari.

En resum, per a la majoria de les configuracions, la carpeta de temes personalitzats és la següent:

Si hi ha múltiples fitxers de tema amb el mateix nom, es carregarà el fitxer amb la revisió més alta.

L'estructura d'un fitxer JSON s'explica al seu lloc web. Bàsicament, un fitxer de format JSON consta de:

En aquest article s'utilitzaran les nomenclatures «clau», «valor», «objecte» i «matriu». Si és la primera vegada que treballeu amb fitxers JSON, comprendre'ls és tan senzill com mirar els exemples que hi ha a continuació.

L'objecte arrel del fitxer JSON de tema de color conté les claus d'esquema següents:

El llenguatge JSON no admet comentaris. No obstant això, podeu fer servir la clau opcional _comments en l'objecte arrel per a escriure els comentaris, per exemple, si esteu adaptant un tema existent, podeu posar l'URL del repositori original. La forma més pràctica és utilitzar una matriu de cadenes.

A continuació es mostra un fitxer d'exemple per al tema «Breeze Light». Podeu observar que, per a evitar que l'exemple sigui massa gran, els objectes editor-colors i text-styles no contenen totes les claus requerides. Podeu veure tot el fitxer del tema «Breeze Light» al repositori de KSyntaxHighlighting.

{
    "_comments": [
        "Aquest és un comentari.",
        "Si aquest tema és una adaptació d'un altre, poseu l'enllaç cap al repositori 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",
        Les altres claus per al color de l'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"
        },
        Les altres claus per a l'estil del text...

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

L'objecte JSON de la clau de metadata conté informació rellevant sobre el tema. Aquest objecte té les següents claus:

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

Correspon als colors de l'àrea per a l'edició de text.

En el fitxer de tema JSON, la clau respectiva editor-colors té com a valor un objecte on cada clau fa referència a un color d'atribut de l'editor de text. Aquí, totes les claus disponibles són obligatòries, els seus valors són cadenes amb codis de color en hexadecimal, com «#00B5CF».

A la IGU per a gestionar els temes de KTextEditor, aquests atributs es poden modificar a la pestanya Colors.

Les claus disponibles són les següents; les claus utilitzades en el fitxer JSON es llisten en negreta, els noms utilitzats a la IGU es mostren entre parèntesis.

Els estils predeterminats del text són heretats pels estils del text ressaltat, el qual permet a l'editor presentar el text d'una manera molt coherent, per exemple, el text dels comentaris utilitza el mateix estil en gairebé tots els formats de text que pot ressaltar el KSyntaxHighlighting.

En el fitxer JSON, la clau respectiva text-styles té com a valor un objecte on cada clau correspon al nom d'un estil predeterminat de text, el qual és equivalent a l'utilitzat en les definicions de ressaltat de la sintaxi. Aquí, totes les claus d'estil de text disponibles són obligatòries, es llisten a continuació.

"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"
    },
    Les altres claus de l'estil de text...
}

A la IGU per a gestionar els temes de color de KTextEditor, aquests atributs es poden modificar a la pestanya Estils predeterminats de text. El nom de la llista d'estils utilitza l'estil configurat per a l'element, el qual proporciona una vista prèvia immediata en configurar un estil. Cada estil permet seleccionar atributs comuns, així com els colors de primer pla i de fons. Per a treure un color de fons, feu clic dret per a emprar el menú contextual.

Les claus d'estil de text disponibles són les següents; les claus utilitzades en el fitxer JSON es llisten en negreta, els noms utilitzats en la IGU es mostraran entre parèntesis si són diferents.

Aquí podreu establir els estils de text per a una definició específica del ressaltat de la sintaxi, superposant l'estil de text predeterminat descrit a la secció anterior.

En el fitxer de tema JSON, això es correspon amb la clau custom-styles, el valor és un objecte on cada clau de subesquema es correspon amb el nom d'una definició de ressaltat de la sintaxi. El seu valor és un objecte on cada clau es refereix al nom dels atributs d'estil definit en els elements itemData del fitxer XML de ressaltat de la sintaxi, i el valor respectiu és un subobjecte amb les claus text-color, selected-text-color, bold, italic, underline, strike-through, background-color i selected-background-color definides a la secció anterior. Cadascun d'aquests valors és opcional, ja que si no hi són presents, es considerarà l'estil establert a text-styles.

Per exemple, en aquest fragment de codi, la definició de ressaltat de la sintaxi «ISO C++» té un estil de text especial per als atributs «Modificadors de tipus» i «Classes estàndard». En el fitxer XML corresponent «isocpp.xml», l'atribut definit «Classes estàndard» utilitza l'estil predeterminat BuiltIn (o dsBuiltIn). En aquest atribut, només se sobreescriurà el valor de text-color amb el nou color «#6431b3».

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

A la IGU per a gestionar els temes de KTextEditor, aquests atributs es poden modificar a la pestanya Estils del text ressaltat. De manera predeterminada, l'editor preselecciona el ressaltat del document actual. Notareu que molts ressaltats contenen altres ressaltats representats per grups en la llista d'estils. Per exemple, la majoria dels ressaltats importen el ressaltat «Alert», i molts formats de codi font importen el ressaltat «Doxygen».

Per a crear un tema nou, primer cal copiar-ne un d'existent. Seleccioneu un tema existent que voleu utilitzar com a base, com el «Brisa clar» o «Brisa fosca» i feu clic a Copia. Després escriviu un nom per al tema nou.

Si voleu modificar un tema integrat o només de lectura, primer l'haureu de copiar amb un nom diferent.

Amb el botó Exporta podreu exportar un tema seleccionat (inclosos els integrats) a un fitxer JSON amb l'extensió .theme. Això obrirà un diàleg per a desar el fitxer. Per a afegir un tema de color des d'un fitxer JSON extern, senzillament premeu el botó Importa i seleccioneu el fitxer .theme des del diàleg.

Un aspecte important en treballar amb els temes de color és triar un contrast de text que faciliti la lectura, especialment en combinació amb el fons.

L'aplicació Kontrast és un verificador del contrast de color. Us indicarà que les combinacions del color de text i color de fons són llegibles i accessibles, de manera que aquesta és una excel·lent eina per a ajudar-vos a crear temes de color.

Podeu descarregar el Kontrast des del lloc web d'aplicacions del KDE o des del paquet Flatpak a Flathub (només a GNU/Linux).

L'aplicació Contrast de GNOME és similar. Podeu descarregar el paquet Flatpak a Flathub (només en GNU/Linux).

Un script en Python al repositori de ressaltat de la sintaxi us permet visualitzar tots els colors d'un tema, així com el contrast amb els diversos fons configurats.

El KSyntaxHighlighting inclou més de 300 definicions de ressaltat de la sintaxi, de manera que és ideal assegurar-vos que el nou tema es vegi bé en totes les definicions de ressaltat de la sintaxi. Els temes de color integrats tenen les següents similituds que es recomana (però no és obligatori) seguir per a aconseguir una visualització correcta de totes les definicions de ressaltat de la sintaxi:

La majoria dels ressaltadors de la sintaxi estan pensats perquè es vegi bé en els temes predeterminats «Brisa clara» i «Brisa fosca», per tant, una altra forma de mantenir la coherència és utilitzar colors similars en els estils de text, com el green per a «Preprocessor» i «Others», blue per a «DataType» i «Attribute», o purple per a «Function».

Recordeu que aquestes recomanacions no són obligatòries quan es crea i publica un tema.