Цветовые схемы хранятся в файлах формата JSON с расширением .theme.

В хранилище исходного кода KSyntaxHighlighting файлы JSON встроенных схем располагаются в каталоге data/themes/. Обратите внимание, что в текстовых редакторах встроенные схемы скомпилированы в библиотеку KSyntaxHighlighting.Поэтому для доступа к ним требуется исходный код или выполнение экспорта из графического интерфейса управления схемами KTextEditor.

Также возможно легко добавлять дополнительные или пользовательские схемы, которые будут загружаться из файловой системы компьютера. Пользовательские файлы схем расположены в каталоге org.kde.syntax-highlighting/themes/ в папке пользователя (её расположение возможно определить с помощью команды qtpaths --paths GenericDataLocation, обычно это $HOME/.local/share/ и /usr/share/).

В случае пакетов Flatpak и Snap расположение данных различается в зависимости от конкретного приложения. В приложении Flatpak расположением пользовательских файлов схем обычно является $HOME/.var/app/название-пакета-flatpak/data/org.kde.syntax-highlighting/themes/, а в приложении Snap — $HOME/snap/название-пакета-snap/current/.local/share/org.kde.syntax-highlighting/themes/.

В Windows® эти файлы хранятся в %USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\themes. %USERPROFILE% обычно имеет значение C:\Users\пользователь.

В целом, для большинства конфигураций каталогом пользовательских схем будет:

Если имеется несколько файлов схем с одним и тем же именем, будет загружен файл с наибольшим значением атрибута revision.

Описание структуры файла JSON приводится на соответствующем веб-сайте. Как правило, файл формата JSON состоит из следующих компонентов:

В этом руководстве используются термины «ключ», «значение», «объект» и «массив». Если пользователь не работал с файлами JSON ранее, понять эту терминологию помогут приведённые далее примеры.

Корневой объект файла JSON цветовой схемы содержит следующие ключи схемы:

Язык JSON не поддерживает комментарии. Тем не менее, для записи комментариев возможно использовать необязательный ключ _comments в корневом объекте. Например, если выполняется адаптация существующей схемы, можно добавить URL-адрес исходного репозитория. Наиболее практичным способом комментирования является использование массива строк.

Далее приводится пример для схемы «Breeze, светлый вариант». Как можно заметить, объекты editor-colors и text-styles содержат не все необходимые ключи (чтобы пример не был слишком большим). Ознакомиться со всем кодом схемы «Breeze, светлый вариант» возможно в репозитории KSyntaxHighlighting.

{
    "_comments": [
        "This is a comment.",
        "If this theme is an adaptation of another, put the link to the original repository."
    ],
    "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",
        Другие ключи цвета редактора...

    },
    "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"
        },
        Другие ключи стиля текста...

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

Объект JSON ключа metadata содержит соответствующую информацию о схеме. Этот объект имеет следующие ключи:

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

Соответствует цветам области редактирования текста.

В файле JSON схемы значением соответствующего ключа editor-colors являетсяобъект, в котором каждый ключ указывает цвет атрибута в текстовом редакторе. Здесь все доступные ключи являются обязательными. Их значения представляют собой строки шестнадцатеричных цветовых кодов, например «#00B5CF».

В графическом интерфейсе для управления схемами KTextEditor эти атрибуты возможно изменить на вкладке Цвета.

Доступны следующие ключи; ключи, используемые в файле JSON, выделены полужирным, названия, используемые в графическом интерфейсе, указаны в скобках.

Типовые стили текста наследуют свои свойства от стилейподсвеченного текста, что дает редактору возможность показывать текст согласованным образом. Например, для текста комментариев используется один и тот же стиль почти во всех форматах текста, которые может подсвечиватьKSyntaxHighlighting.

В файле JSON значением соответствующего ключаtext-styles является объект, каждый ключ которого соответствует названию типового стилятекста. Ключи являются эквивалентами ключей, которые используются вопределениях подсветки синтаксиса. Здесь все доступные ключистиля текста обязательны. Список ключей приведён далее.

"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"
    },
    Другие ключи стиля текста...
}

В графическом интерфейсе управления схемами цветов KTextEditor эти атрибуты можно изменить на вкладке Стиль текста. Для названия в списке стилей используется стиль для соответствующей записи. Это позволяет сразу увидеть результат применения стиля. В каждом стиле возможно выбрать общие атрибуты, а также цвета текста и фона. Чтобы сбросить цвет фона, щёлкните правой кнопкой мыши и воспользуйтесь контекстным меню.

Доступны следующие ключи стиля текста; ключи, используемые в файле JSON, выделены полужирным, названия, используемые в графическом интерфейсе, указаны в скобках, если они отличаются.

Здесь возможно установить стили текста для конкретного определения синтаксиса, переопределив типовой стиль текста, который описан в предыдущемразделе.

В файле JSON схемы этот ключ соответствует ключу custom-styles, значением которого является объект, каждый ключ подчинённой схемы которого соответствует названию определения подсветки синтаксиса. Его значением является объект, каждый ключ которого соответствуетназванию атрибутов стиля, определённому в элементах itemDataфайла XML подсветки синтаксиса, и соответствующее значение является подчинённым объектом с ключами text-color, selected-text-color, bold, italic,underline, strike-through,background-color и selected-background-color, определённым в предыдущем разделе. Все эти значения необязательны, поскольку, если они не указаны, будет использован стиль, определённый в text-styles.

Например, в этом фрагменте кода определение подсветки синтаксиса «ISO C++» содержит специальный стиль текста для атрибутов «Type Modifiers» и «Standard Classes». В соответствующем файле XML «isocpp.xml» для определённого атрибута «Standard Classes» используется типовой стиль BuiltIn (или dsBuiltIn). В этом атрибуте будет перезаписано только значение text-color — новым цветом «#6431b3».

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

В графическом интерфейсе управления схемами KTextEditor эти атрибуты можно изменить на вкладкеДля отдельных форматов. Обычно редактор предварительно выбирает подсветку для текущего документа. Многие определения подсветок содержат другие определения подсветок, обозначаемые группами в списке стилей. Например, большинство определений подсветок импортируют подсветку «Alert», а многие форматы исходного кода импортируютподсветку «Doxygen».

Чтобы создать новую схему, необходимо сначала скопировать существующую. Выберите существующую схему, которую следует использовать в качестве основы (например, «Breeze, светлый вариант» или «Breeze, тёмный вариант»), и нажмите кнопку Копировать…. Затем укажите название новой схемы.

Чтобы изменить встроенную или доступную только для чтения схему, необходимо сначала скопировать её, указав для копии другое название.

Выбранную тему (включая встроенные) возможно экспортировать в файл JSON с расширением .theme путём нажатия кнопки Экспорт. Будет открыт диалог сохранения файла. Чтобы добавить цветовую схему из внешнего файла JSON, просто нажмите кнопку Импорт и выберите в диалоге файл .theme.

Важным аспектом работы с цветовыми схемами является выбор контрастного цветатекста, который упростит чтение, особенно в сочетании с цветом фона.

Приложение Kontrast предназначено для проверки контрастности цветов. Эта программа позволяет проверить, является ли сочетание цвета текста и цвета фона хорошо читаемым, что облегчает создание цветовых схем.

Программу Kontrast возможно загрузить на веб-сайте приложений KDE или установить из пакета Flatpak на Flathub (только в GNU/Linux).

Приложение GNOME Contrast работает аналогичным образом. Возможно загрузить пакет Flatpak на Flathub (только в GNU/Linux).

KSyntaxHighlighting включает более 300 определений подсветки синтаксиса; желательно убедиться, что новая схема выглядит хорошо во всех определениях подсветки синтаксиса. Во встроенных цветовых темах использованы следующие принципы, которыми рекомендуется (но не обязательно) пользоваться для корректного отображения всех определений подсветки синтаксиса:

Большинство подсветок синтаксиса хорошо выглядят в типовых схемах «Breeze, светлый вариант» и «Breeze, тёмный вариант». Следовательно, ещё одним способом обеспечения согласованности является использование похожих цветов в стилях текста. Например, зелёного для «Preprocessor» и «Others», синего для «DataType» и «Attribute» или фиолетового для «Function».

Обратите внимание, что эти рекомендации не обязательно соблюдать при создании и публикации схемы.