I temi di colori sono memorizzati in file in formato JSON con l'estensione .theme.

Nel codice sorgente di KSyntaxHighlighting i file JSON dei temi incorporati sono nella cartella data/themes/. Nota che negli editor di testo i temi incorporati sono compilati nella libreria KSyntaxHighlighting, quindi il modo per accedervi è tramite il codice sorgente oppure esportandoli dalla GUI che gestisce i temi di KTextEditor.

È anche possibile aggiungere facilmente dei temi aggiuntivi o personalizzati, che vengono caricati dal file system. I file dei temi personalizzati dall'utente si trovano nella cartella org.kde.syntax-highlighting/themes/ che si trova nella cartella utente e vengono trovati col comando qtpaths --paths GenericDataLocation; di solito sono $HOME/.local/share/ e /usr/share/.

Per i pacchetti Flatpak e Snap la cartella qui sopra non funzionerà perché la posizione dei dati è diversa per ogni applicazione. In un'applicazione Flatpak generalmente la posizione dei file dei temi personalizzati è $HOME/.var/app/nome-del-pacchetto-flatpak/data/org.kde.syntax-highlighting/themes/, mentre in una Snap è $HOME/snap/nome-del-pacchetto-snap/current/.local/share/org.kde.syntax-highlighting/themes/.

In Windows® questi file si trovano in %USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\themes. %USERPROFILE% viene generalmente espanso in C:\Users\utente.

In sintesi, per la maggior parte delle configurazioni la cartella dei temi personalizzati è la seguente:

Se esistono più temi con lo stesso nome, verrà caricato quello che ha il valore più alto dell'attributo revision.

La struttura di un file JSON è spiegata nel loro sito web. Fondamentalmente il formato di file JSON consiste in:

In questo articolo verrà usata la nomenclatura «chiave», «valore», «oggetto» e «vettore». Se è la prima volta che lavori con i file JSON la loro comprensione è semplice come guardare l'esempio qui sotto,

L'oggetto principale del file del tema di colori JSON contiene il seguente schema di chiavi:

Il linguaggio JSON non supporta i commenti, tuttavia puoi usare la chiave facoltativa _comments nell'oggetto principale per scrivere dei commenti; ad esempio, se stai adattando un tema esistente puoi mettere l'URL del deposito. Il modo più pratico è quello di usare un vettore di stringhe.

Qui sotto c'è un file di esempio del tema «Brezza chiaro». Puoi notare che, per evitare che l'esempio sia troppo lungo, gli oggetti editor-colors e text-styles, non contengano tutte le chiavi richieste. Puoi vedere l'intero archivio del tema «Brezza chiaro» nel deposito di KSyntaxHighlighting.

{
    "_comments": [
        "Questo è un commento.",
        "Se questo tema è un adattamento di un altro, inserisci il collegamento alla sorgente d'installazione originale."
    ],
    "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",
        Le altre chiavi dei colori dell'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"
        },
        Le altri chiavi di stile del testo...

    },
    "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'oggetto JSON della chiave metadata contiene informazioni rilevanti sul tema. Questo oggetto ha le seguenti chiavi:

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

Corrisponde ai colori dell'area di modifica del testo.

Nel file di tema JSON la rispettiva chiave editor-colors ha come valore un oggetto nel quale ciascuna chiave fa riferimento ad un attributo di colore dell'editor di testo. Qui tutte le chiavi disponibili sono obbligatorie: i loro valori sono delle stringhe con i codici esadecimali dei colori, ad esempio «#00B5CF».

Nell'GUI per gestire i temi di KTextEditor questi attributi possono essere modificati nella scheda Colori.

Le chiavi disponibili sono le seguenti: quelle usate nel file JSON sono elencate in grassetto, mentre i nomi usati nell'GUI vengono mostrati tra parentesi.

Gli stili di testo predefiniti sono ereditati dagli stili di evidenziazione del testo, permettendo all'editor di presentare il testo in modo coerente; ad esempio, il testo dei commenti è uguale in quasi tutti i formati di testo che KSyntaxHighlighting può evidenziare.

Nel file JSON la rispettiva chiave text-styles ha come valore un oggetto nel quale ogni chiave corrisponde al nome di uno stile di testo predefinito, che sono equivalenti a quelli usati nelle definizioni di evidenziazione della sintassi. Qui tutti le chiavi dello stile del testo disponibili sono obbligatorie ; queste sono elencate di seguito.

"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"
    },
    Le altre chiavi di stile del testo...
}

Nell'GUI per gestire i temi di colori di KTextEditor questi attributi possono essere modificati nella scheda Stili di testo predefiniti. Il nome nell'elenco degli stili utilizza lo stile configurato per l'elemento, fornendoti un'anteprima immediata durante la configurazione di uno stile. Ogni stile ti permette di selezionare gli attributi comuni, nonché i colori di primo piano e di sfondo. Per annullare l'impostazione di un colore di sfondo, fai clic con il pulsante destro per utilizzare il menu contestuale.

Le chiavi per lo stile del testo disponibili sono le seguenti: quelle usate nel file JSON sono elencate in grassetto, mentre i nomi usati nell'GUI vengono mostrati tra parentesi se sono diversi.

Qui puoi stabilire gli stili del testo per una definizione di evidenziazione della sintassi specifica, senza tener conto degli stili di testo predefiniti descritti nella sezione precedente.

Nel file di tema JSON questo corrisponde alla chiave custom-styles, il cui valore è un oggetto nel quale ciascuna chiave del sottoschema corrisponde al nome di una definizione di evidenziazione. Il suo valore è un oggetto nel quale ciascuna chiave si riferisce al nome degli attributi di stile definito negli elementi itemData del file XML di evidenziazione della sintassi, e il rispettivo valore è un sotto-oggetto con le chiavi text-color, selected-text-color, bold, italic, underline, strike-through, background-color e selected-background-color, che sono state definite nella sezione precedente. Ciascuno di questi valori è facoltativo, dal momento che viene considerato lo stile impostato in text-styles se non sono presenti.

Ad esempio, in questo pezzetto di codice la definizione di evidenziazione della sintassi di «C++ ISO» ha uno stile del testo speciale per gli attributi «Type Modifiers» e per «Standard Classes». Nel file XML corrispondente «isocpp.xml», l'attributo definito «Standard Classes» utilizza lo stile predefinito BuiltIn (o dsBuiltIn). In questo attributo, solamente il valore di text-color è sovrascritto dal nuovo colore «#6431b3».

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

Nell'GUI per gestire i temi di KTextEditor questi attributi possono essere modificati nella scheda Stili di testo evidenziato. Per impostazione predefinita, l'editor preseleziona l'evidenziazione del documento corrente. Noterai che molti evidenziatori ne contengono altri, rappresentati dai gruppi nell'elenco degli stili. Ad esempio, la maggior parte degli evidenziatori importa «Alert», mentre molti dei formati di codice sorgente importano «Doxygen».

Per creare un nuovo tema è necessario prima copiarne uno esistente. Selezionane uno che vuoi usare come base, ad esempio «Brezza chiaro» o «Brezza scuro», e fai clic su Copia. Scrivi quindi il nome del nuovo tema.

Se vuoi modificare un tema integrato o a sola lettura, è necessario prima copiarlo con un nome diverso.

Puoi esportare un tema selezionato (inclusi quelli incorporati) in un file JSON con l'estensione .theme per mezzo del pulsante Esporta: si aprirà una finestra per salvare il file. Per aggiungere un tema di colori da un file JSON, premi semplicemente il pulsante Importa e seleziona il file .theme dalla finestra.

Un aspetto importante quando si lavora coi temi di colori è quello di scegliere un contrasto del testo che renda più semplice la lettura, specialmente in combinazione con lo sfondo.

L'applicazione Kontrast è un controllore del contrasto: ti dice se le combinazioni di colore del testo e dello sfondo sono leggibili e accessibili, quindi è un eccellente strumento che ti aiuta a creare i temi di colori.

Puoi scaricare Kontrast dal sito web delle applicazioni di KDE o dal pacchetto Flatpak su Flathub (solo in GNU/Linux).

L'applicazione Contrast di GNOME è simile. Puoi scaricare il pacchetto Flatpak su Flathub (solo in GNU/Linux).

Uno script python nel deposito di evidenziazione della sintassi ti permette di visualizzare tutti i colori del tema, oltre al contrasto con i vari sfondi configurati.

KSyntaxHighlighting include più di 300 definizioni di evidenziazione della sintassi, quindi dovresti assicurarti che il tuo nuovo tema vada bene con tutte le definizioni di evidenziazione della sintassi. I temi di colori integrati hanno le similarità seguenti, che è raccomandabile (ma non obbligatorio) seguire per ottenere una visualizzazione corretta di tutte le definizioni di evidenziazione della sintassi:

La maggior parte degli evidenziatori di sintassi serve per dare un bell'aspetto nei temi predefiniti, «Brezza chiaro» e «Brezza scuro», quindi un altro modo per mantenere la consistenza è quello di usare dei colori simili negli stili di testo, ad esempio il verde per il «preprocessore» e «altri», il blu per i «tipi di dato» e per gli «attributi», oppure il viola per le «funzioni».

Nota che queste raccomandazioni non sono obbligatorie nella creazione e nella pubblicazione di un tema.